{"_id":"@coderifts/openai-agents","name":"@coderifts/openai-agents","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@coderifts/openai-agents","version":"0.1.0","description":"CodeRifts contract governance for the OpenAI Agents SDK — a tool-input guardrail that gates contract mutations before a tool runs, plus REQUEST_APPROVAL mapped to the SDK's native approval surface.","license":"MIT","type":"module","main":"src/index.mjs","engines":{"node":">=20"},"scripts":{"test":"node --test \"test/*.test.mjs\""},"peerDependencies":{"@openai/agents":">=0.17.0"},"dependencies":{"@coderifts/contract-path":"^1.0.0","@coderifts/sdk":">=3.6.0"},"keywords":["coderifts","openai-agents","guardrail","api-governance"],"gitHead":"96f83738fe0904635c6ed780d1aad501a0b1f478","_id":"@coderifts/openai-agents@0.1.0","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-wVBU0kKWiVqQgW5fFlUcdnkf/PYyfnhrxXA4hevC/vLeq6x45TLz2cTFGlaTVuLh0HAvu7dj+69G9XEd/wAs2g==","shasum":"5c6edb7fd4dcf2d84a7e0266fde889aae5fa023d","tarball":"https://registry.npmjs.org/@coderifts/openai-agents/-/openai-agents-0.1.0.tgz","fileCount":5,"unpackedSize":31410,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHO0QRkBDZ7TZuQAtJXGw/9gNvST2EnOKSpBjMYyu61NAiBy9gJrRgMspGb1VsndVwBvWwD2Of/rqcSTPsdoRkPk+w=="}]},"_npmUser":{"name":"zsobpeter","email":"zsobpeter@gmail.com"},"directories":{},"maintainers":[{"name":"zsobpeter","email":"zsobpeter@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openai-agents_0.1.0_1787599176561_0.013334924068298504"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-24T19:19:36.475Z","0.1.0":"2026-08-24T19:19:36.713Z","modified":"2026-08-24T19:19:36.937Z"},"maintainers":[{"name":"zsobpeter","email":"zsobpeter@gmail.com"}],"description":"CodeRifts contract governance for the OpenAI Agents SDK — a tool-input guardrail that gates contract mutations before a tool runs, plus REQUEST_APPROVAL mapped to the SDK's native approval surface.","keywords":["coderifts","openai-agents","guardrail","api-governance"],"license":"MIT","readme":"# @coderifts/openai-agents\n\nCodeRifts contract governance for the [OpenAI Agents SDK](https://openai.github.io/openai-agents-js/).\n\nA **tool-input guardrail** decides, before a tool runs, whether the call is a governed contract\nmutation. It gates a tool **even when CodeRifts never wrapped that tool's implementation** — so you\ncan govern third-party or hand-written tools you do not own.\n\n## Install\n\n```bash\nnpm install @coderifts/openai-agents @openai/agents @coderifts/sdk\n```\n\n`@openai/agents` is a **peer** dependency (>=0.17.0); `@coderifts/sdk` is a dependency.\n\n## Use\n\n```js\nimport { Agent, run, tool } from '@openai/agents';\nimport { CodeRifts } from '@coderifts/sdk';\nimport { withCodeRiftsGuardrail } from '@coderifts/openai-agents';\n\nconst client = new CodeRifts({ apiKey: process.env.CODERIFTS_API_KEY });\nconst { guardrail, needsApproval } = withCodeRiftsGuardrail({\n  client,\n  operation: 'merge',\n  readPrior: (p) => fs.readFileSync(p, 'utf8'),   // the `before` side\n});\n\nconst writeFile = tool({\n  name: 'write_file',\n  description: 'Write a file.',\n  parameters: z.object({ path: z.string(), content: z.string() }),\n  inputGuardrails: [guardrail],\n  needsApproval,                                   // REQUEST_APPROVAL suspends for a human\n  execute: async ({ path, content }) => { /* ... */ },\n});\n```\n\n`attachGuardrailToEach(tools, guardrail)` attaches it across a list you already have.\n\n## Verdict mapping\n\n| `execution_action` | Behaviour |\n|---|---|\n| `CONTINUE`, `CONTINUE_WITH_MONITORING` | `allow()` — the tool runs |\n| `REQUEST_APPROVAL` | guardrail allows, `needsApproval` returns true → the SDK emits a `RunToolApprovalItem` and **suspends for a human** |\n| `STOP` / `BLOCK` | `rejectContent()` with the WHY + remediation |\n| anything unrecognised | `rejectContent()`, message names it as *not permission (fail closed)* |\n| unreadable arguments / missing path on a mutator | `rejectContent()` fail-closed |\n| non-contract path, read-only tool | `allow()` with **no API call** |\n\n`rejectContent`, not `throwException`: a governance deny must **teach**. `throwException` aborts the\nwhole run with a tripwire and the model learns nothing.\n\n**One preflight per tool call.** The guardrail and the `needsApproval` resolver share a memo keyed\nby the SDK's `callId`, so enabling approvals does not double your API spend.\n\n## Coverage\n\nWith the CodeRifts guardrail attached to a tool, that tool is governed **even if CodeRifts never\nwrapped its implementation** — so an agent can adopt governance for third-party or hand-written\ntools it does not own, and a blocked contract change returns the reason and remediation to the model\nrather than failing opaquely. The claim changes from *per-table* to *per-tool-with-guardrail* —\n**not** to per-agent: tool input guardrails are attached per tool, there is no agent-wide form, and\nwe demonstrated that the same ungoverned tool still mutates an OpenAPI spec when the guardrail is not\nattached to it. Handoff sub-agents, hosted tools, and direct client calls outside `run()` remain\nungated. Enforcement independent of the developer's diligence still lives downstream, at the\ncontract-gate on the pull request and the deploy-gate in CI.\n\n### What this does not cover\n\n1. **Tools without the guardrail attached.** There is no agent-wide form — `'toolInputGuardrails' in\n   agent` is `false`, and the Agent's `inputGuardrails` is a different type that validates the\n   agent's *input*, not tool calls. `attachGuardrailToEach` covers exactly the list you pass it.\n2. **Handoff sub-agents.** A sub-agent's tools are separate tool objects and do not inherit it.\n3. **Hosted / built-in tools** (`codeInterpreterTool`, `applyPatchTool`). Built by SDK factories;\n   you would have to interpose your own wrapper to add `inputGuardrails`.\n4. **Direct client calls outside `run()`.** They never reach the runner, so no guardrail fires.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-ec7b716fbd90fe84e64d9ee4a41c1f34"}