workspai 0.75.2 → 0.77.0

package/docs/agent-framework-adapters.md

@@ -12,23 +12,35 @@ existing project ---/            |
                                   -> Workspai Context, Goal, PCC, and Verify
 ```
 
-Microsoft Agent Framework is the first concrete implementation of this
+Microsoft Agent Framework is the first adapter implementation of this
 foundation. Its Python and .NET adapters are intentionally separate because
 their package graphs, runtime requirements, entrypoints, and verification
-commands differ. Both are available for governed attachment after their exact
-manifest digests pass the required Linux, macOS, and Windows conformance lanes
-and are bound into the reviewed release-admission inventory.
+commands differ. Both become available for governed attachment only after the
+exact manifest and release baseline pass the required Linux, macOS, and Windows
+conformance lanes and are bound into the reviewed release-admission inventory.
+Per-platform semantic implementation digests accompany that evidence for
+traceability, but do not act as runtime authorization locks.
+
+OpenAI Agents SDK adapters for Python and TypeScript are implemented in the
+same registry and lifecycle. They become Create/Attach kits only after their
+complete cross-platform matrix is reviewed into that inventory. Public
+commands fail closed rather than silently substituting Microsoft, OpenAI, or
+another runtime.
+
+OpenRouter Client SDK access belongs to the [AI Gateway](./model-gateways.md)
+category. Do not add OpenRouter under Agent Frameworks, and do not use
+`@openrouter/agent` to implement a gateway kit.
 
 ## Published contracts
 
-| Contract                                                                       | Purpose                                                                               |
-| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
-| `contracts/agent-framework-capabilities.v1.json`                               | Normative ownership, capability, lifecycle, security, versioning, and admission rules |
-| `contracts/workspace-intelligence/agent-framework-adapter-manifest.v1.json`    | JSON Schema for one framework/version adapter declaration                             |
-| `contracts/workspace-intelligence/agent-framework-conformance-report.v1.json`  | JSON Schema for reproducible adapter admission evidence                               |
-| `contracts/workspace-intelligence/agent-framework-change-plan.v1.json`         | Portable, mutation-free scaffold or attach plan returned to the host                  |
-| `contracts/workspace-intelligence/agent-framework-ownership-receipt.v1.json`   | Hash-bound proof of the files Workspai may safely refresh                             |
-| `contracts/workspace-intelligence/agent-framework-admission-candidate.v1.json` | Review-pending, digest-bound index of the complete cross-platform evidence matrix     |
+| Contract                                                                       | Purpose                                                                                  |
+| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `contracts/agent-framework-capabilities.v1.json`                               | Normative ownership, capability, lifecycle, security, versioning, and admission rules    |
+| `contracts/workspace-intelligence/agent-framework-adapter-manifest.v1.json`    | JSON Schema for one framework/version adapter declaration                                |
+| `contracts/workspace-intelligence/agent-framework-conformance-report.v2.json`  | JSON Schema binding reproducible adapter evidence to manifest and implementation digests |
+| `contracts/workspace-intelligence/agent-framework-change-plan.v1.json`         | Portable, mutation-free scaffold or attach plan returned to the host                     |
+| `contracts/workspace-intelligence/agent-framework-ownership-receipt.v1.json`   | Hash-bound proof of the files Workspai may safely refresh                                |
+| `contracts/workspace-intelligence/agent-framework-admission-candidate.v2.json` | Review-pending, digest-bound index of the complete cross-platform evidence matrix        |
 
 The schemas are also discoverable through
 `contracts/published-contract-catalog.v1.json` and the extension compatibility
@@ -109,16 +121,38 @@ Generated starter files use an isolated `agents/<instance>` root and keep
 adapter state under `.workspai/agent-frameworks/<adapter>/<instance>.json`.
 That instance contains the only runtime dependency manifest; the project root
 does not receive an empty Python or .NET manifest that could be mistaken for a
-second executable unit. Workspace Model reports these projects as `agent`,
+second executable unit. Python and .NET starters resolve bounded context from
+the directory that owns `agents/<instance>/`. They do not use process cwd.
+`workspace run start` executes from the agent package directory and still
+finds `.workspai/reports/project-context-agent.json` at the project root.
+Loaders share the OpenAI containment contract: canonical path walk, regular-file
+open, 128 KiB cap, UTF-8 JSON, and `schemaVersion: project-context-agent.v1`.
+The Python starter is pip-editable (`[build-system]` + setuptools modules) and
+uses the official Foundry hello-world `Agent(client=FoundryChatClient(...))`
+pattern with three read-only documented tools: `describe_workspai_context`,
+`read_workspai_project_summary`, and `list_workspai_supported_commands`. The
+.NET starter uses `AIProjectClient.AsAIAgent` plus `AIFunctionFactory.Create`,
+enables `RestorePackagesWithLockFile`, and does not emit invented NuGet lock
+hashes. Neither starter pastes admitted JSON into instructions; live
+entrypoints stream stdout and accept a prompt from argv or stdin. Neither
+starter hardcodes a Foundry model name; `FOUNDRY_MODEL` is
+required. `DefaultAzureCredential` remains the local development convenience
+Microsoft documents; generated READMEs tell production hosts to prefer
+`ManagedIdentityCredential`. Adapters remain `preview`. Unsupported Microsoft
+primitives (durable workflows, MCP, HITL loops, hosted tools) stay out of the
+generated first-version scaffold.
+Workspace Model reports these projects as `agent`,
 retains `microsoft-agent-framework` as their framework identity, and reports
 only lifecycle stages backed by concrete manifests, entrypoints, tests, or an
 owned project runner.
 Each starter also includes credentialless tests for the bounded context
-boundary and an environment-name example with no secret values. Python uses
-the host platform's normal Python 3 launcher and remains dependency-free for
-these tests; .NET uses a separately pinned test project. The conformance matrix
-executes these tests in addition to compiling and exercising the deterministic
-framework lifecycle.
+boundary, allowlisted views, and Azure-shaped redaction, plus an
+environment-name example with no secret values. Python context
+tests isolate the operational context file and restore it afterward; they stay
+dependency-free unless `agent-framework` is installed for the optional
+LocalChatClient loop. .NET uses a separately pinned test project. The conformance
+matrix executes these tests in addition to compiling and exercising the
+deterministic framework lifecycle.
 Existing user-authored files are blockers, never overwrite targets. A managed
 comment alone does not prove ownership: refresh also requires the previous
 Workspai ownership receipt, which is bound to the exact adapter-manifest digest;
@@ -127,18 +161,100 @@ Provider credentials remain environment references. The first provider profile u
 Microsoft Foundry, but provider identity is not part of framework identity and
 additional profiles must preserve the same security boundary.
 
-A path-filtered six-lane adapter matrix compiles the generated Python and .NET
-projects on Linux, macOS, and Windows. Every lane records all 18 mandatory
-checks, the exact runtime and framework baseline, a digest of the adapter
-manifest, and one bounded evidence file per check. Reports are retained as CI
-artifacts for review. A final job validates every evidence path and admits the
-matrix only when all three operating-system lanes pass for both adapters.
+## OpenAI Agents SDK baseline
+
+The built-in OpenAI adapters pin independently verified SDK baselines. They do
+not reuse Microsoft detection, kits, or model-provider defaults.
+
+| Adapter                    | Tested framework | Runtime         | Authored detection                 |
+| -------------------------- | ---------------- | --------------- | ---------------------------------- |
+| `openai-agents-python`     | `0.22.2`         | Python `>=3.10` | exact PyPI package `openai-agents` |
+| `openai-agents-typescript` | `0.18.0`         | Node.js `>=22`  | exact npm package `@openai/agents` |
+
+The TypeScript starter also pins peer `zod` `4.6.5`, TypeScript `5.9.3`, and
+`@types/node` `22.20.3`. The `openai` PyPI or npm package alone is not this
+framework. Generated markers under `.workspai/agent-frameworks/` cannot select
+it.
+
+Generated loaders resolve the Workspai project as the directory that owns
+`agents/<instance>/`. They do not use process cwd, unbounded ancestor search,
+or a copied context file inside the agent package. Canonical containment,
+a regular-file open (`O_NOFOLLOW` when the platform provides it), the 128 KiB
+cap, UTF-8 JSON, and `schemaVersion: project-context-agent.v1` are enforced in
+the starter. Generation, freshness, and integrity remain host-owned agent-sync
+work. Internal symlinks, including Windows reparse points treated as links, are
+allowed only when every resolved hop stays inside the project root. Diagnostics
+do not include file contents.
+
+The loader walk is not an atomic open. Between `lstat` of one hop and `open` of
+the next, a local actor who can replace a path component may still race the
+walk. The bound we claim, and only that bound, is: after a successful open with
+`O_NOFOLLOW` when the kernel provides it, that file descriptor is `fstat`'d and
+at most 128 KiB is read from that descriptor. This is not a proof of complete
+TOCTOU immunity, of Windows junction behavior on every host, or of
+enterprise-grade isolation.
+
+Claimed capabilities are conservative and independently evidenced:
+
+- native: `single-agent`, `typed-tools`, `local-execution`
+- conditional: `telemetry` (defaults off; `WORKSPAI_AGENT_TRACING=1` opts in;
+  `OPENAI_AGENTS_DISABLE_TRACING=1|true` keeps tracing off even if the opt-in
+  is set), `provider-neutral-models` (starter only reads `OPENAI_MODEL` /
+  `OPENAI_DEFAULT_MODEL`)
+- unsupported in this version: handoffs, MCP, sessions/resume, voice, sandbox,
+  hosted tools, and human-approval loops
+
+Python cancellation uses `Runner.max_turns` and `ModelSettings.timeout` from
+`openai-agents` `0.22.2`. `ModelSettings.timeout` is a per-model-request
+timeout applied only on the live model path. Injected `ScriptedModel` runs omit
+it because that setting hung the official test double on Python 3.13.
+TypeScript cancellation uses `maxTurns` plus `AbortSignal` from
+`@openai/agents` `0.18.0`. Those SDK controls are not a Workspai-owned timeout
+service. Workspai still owns mutation admission and verification; a successful
+model run is not verified evidence.
+
+Generated starters do not paste `project-context-agent.json` into model
+instructions. They expose three read-only tools over allowlisted views:
+context size and `schemaVersion`, workspace/project identity (including
+`boundedGraphSearch` as a pointer, not a shell), and the admitted command
+surface. Live Python uses `Runner.run_streamed`; live TypeScript streams
+`Runner.run({ stream: true })`. Credentialless ScriptedModel tests stay on
+the non-stream `run` path. A prompt is taken from argv or stdin.
+
+Generated OpenAI context tests copy the operational
+`.workspai/reports/project-context-agent.json` aside for the suite and restore
+it afterward. A green test run is not allowed to delete or replace that host
+artifact.
+
+Create lists every published agent kit under **AI Agent**, including
+`agent.openai.python` and `agent.openai.typescript`. That picker is the
+published catalog: it is not filtered by release-admission digest match or
+workspace profile. A later adapter-manifest change must not hide a kit.
+Create and Attach still refuse a kit whose adapter is not release-admitted;
+visibility in the picker is not permission to write a blocked adapter.
+Attach still requires `--framework openai-agents` when the
+runtime is shared. OpenAI adapters are labeled `stable`; release admission
+remains blocked until the exact v2 cross-platform candidate is promoted.
+Handoffs, MCP, sessions, voice, sandbox, and approval loops stay unsupported.
+Microsoft adapters remain `preview`.
+
+A path-filtered PR gate compiles only the affected Microsoft or OpenAI adapter
+family on Linux. Shared lifecycle, security, registry, admission, and contract
+changes select both families; documentation-only edits do not run adapter
+conformance. The complete twelve-lane matrix is an explicit release-
+qualification operation: it compiles Microsoft Python/.NET and OpenAI
+Python/TypeScript on Linux, macOS, and Windows. Every full-qualification lane
+records all 18 mandatory checks, the exact runtime and framework baseline,
+digests of the adapter manifest and semantic implementation, and one bounded
+evidence file per check. Reports are retained as CI artifacts for review. A
+final job validates every evidence path and emits an admission candidate only
+when all three operating-system lanes pass for every built-in adapter.
 Python conformance is pinned to 3.10.11, the final Python 3.10 release with
 cross-platform binary installers; this provides one reproducible minimum-runtime
 baseline while the adapter continues to declare Python `>=3.10` support.
 
 After verification, CI emits one admission-candidate artifact. It binds the
-source commit, CLI version, adapter-manifest digests, lane reports, and every
+source commit, CLI version, adapter manifest and implementation digests, lane reports, and every
 evidence file by SHA-256. Its status is always `pending`: successful CI produces
 reviewable evidence, not release authority. Only the protected version-update
 branch may convert that candidate into the exact release-admission inventory,
@@ -149,11 +265,16 @@ blocked when callers provide neither raw conformance reports nor explicit
 permission to use the bundled reviewed release inventory. User-facing commands
 enable that inventory deliberately and fail closed if an adapter version,
 manifest digest, framework baseline, runtime, or platform list has changed.
+Semantic implementation digests remain in lane reports, candidates, and the
+reviewed inventory as audit provenance. They are verified during full
+qualification and promotion, but are deliberately not runtime authorization:
+routine implementation changes are guarded by affected-family tests instead
+of requiring a hand-edited admission digest for every source edit.
 
 ## Attach an agent runtime
 
-Build current Workspace Intelligence first, then inspect the release-admitted
-runtimes:
+Build current Workspace Intelligence first, then inspect adapter admission
+state:
 
 ```bash
 npx workspai workspace intelligence run --for-agent generic --strict --json
@@ -170,6 +291,11 @@ npx workspai agent framework plan \
   --name support-agent
 ```
 
+When more than one admitted framework shares a runtime, pass `--framework`
+explicitly. Workspai does not guess or fall back. `--runtime python` without
+`--framework` now requires an explicit choice because Microsoft Agent Framework
+and OpenAI Agents SDK are both admitted.
+
 The interactive attach command displays the same plan and asks before granting
 its filesystem effect. Automation must opt in with `--yes` and records the
 identity supplied by `--granted-by`:
@@ -207,8 +333,9 @@ npx workspai create project agent.microsoft.dotnet operations-agent
 Create writes a minimal runtime identity, registers the project, seals a
 Model/Graph baseline so the adapter can plan, applies the adapter-owned scaffold
 inside that Change, then re-observes Model, Graph, and project grounding against
-the nested runtime. The interactive wizard exposes these kits under the **AI
-Agent** category only because they are release-admitted. A failed scaffold
+the nested runtime. The interactive wizard lists every published kit under the
+**AI Agent** category. Scaffolding still requires the selected adapter to be
+release-admitted. A failed scaffold
 rolls back the new directory and workspace registration. Detection itself
 remains read-only and never authorizes writes.
 
@@ -274,10 +401,12 @@ and unadvertised runtimes fail closed.
 
 The generic boundary was hardened against two deliberately different
 integration shapes: a filesystem-first Node.js framework and the
-multi-language Microsoft Agent Framework. Only the Microsoft adapters are
-implemented. They are selectable for Create and Attach only while their exact
-manifest digest, framework baseline, runtime, and platform list remain in the
-reviewed release-admission inventory.
+multi-language Microsoft Agent Framework. OpenAI Agents SDK Python and
+TypeScript adapters now share that same create, attach, detection, ownership,
+and verification host. They are selectable for Create and Attach only after
+their exact manifest digest, framework baseline, runtime, and platform list
+enter the reviewed release-admission inventory. Microsoft adapters remain
+selectable while their current inventory entries stay valid.
 
 ## Implementation sequence
 
@@ -286,13 +415,13 @@ reviewed release-admission inventory.
 2. Use the framework-neutral registry, detector, and bounded manifest loader.
 3. Review the Microsoft Python and .NET digest-bound evidence produced by the
    full conformance matrix.
-4. Keep automated upstream discovery separate from release authority: report
+4. Review the OpenAI Python and TypeScript digest-bound evidence produced by
+   the same matrix; do not treat local Linux success as multi-OS admission.
+5. Keep automated upstream discovery separate from release authority: report
    newer registry versions, then update pins only through a reviewed change.
    Re-run the full matrix before treating a new pin as independently proven.
-5. Admit another framework only after its create and attach paths share these
-   ownership, rollback, and verification guarantees.
 
 AutoGen is not planned as a new-project target because Microsoft Agent
-Framework is its supported successor path. Eve, LangGraph, and OpenAI Agents
-SDK are not advertised; each requires its own adapter, tested baseline, and
-conformance evidence.
+Framework is its supported successor path. Eve and LangGraph are not
+advertised; each requires its own adapter, tested baseline, and conformance
+evidence.

package/docs/ci-workflows.md

@@ -4,33 +4,51 @@ Map of GitHub Actions workflows in this repository. Use this when editing CI to
 
 ## Workflows
 
-| Workflow                 | Path                                                 | Purpose                                                                   |
-| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------- |
-| Build / test matrix      | `.github/workflows/ci.yml`                           | Path-aware docs or full matrix validation plus the required `CI Gate`     |
-| Workspace E2E matrix     | `.github/workflows/workspace-e2e-matrix.yml`         | Cross-OS workspace lifecycle smoke; setup `--warm-deps`; cache/mirror ops |
-| Windows bridge E2E       | `.github/workflows/windows-bridge-e2e.yml`           | Native Windows bridge and lifecycle checks                                |
-| E2E smoke                | `.github/workflows/e2e-smoke.yml`                    | Focused bridge regression smoke                                           |
-| Official generator smoke | `.github/workflows/frontend-generator-smoke.yml`     | Contract-driven official-generator drift gate                             |
-| Agent Framework matrix   | `.github/workflows/agent-framework-conformance.yml`  | Six-lane Python/.NET adapter compile, credentialless lifecycle, admission |
-| Agent Framework discovery| `.github/workflows/agent-framework-version-discovery.yml` | Weekly PyPI/NuGet candidate report; no commit, PR, or contract rewrite |
-| Security                 | `.github/workflows/security.yml`                     | Path-aware scanning plus the always-resolved `Security Gate`              |
-| Manual npm release       | `.github/workflows/release-npm-manual.yml`           | Maintainer-only release gate and publish workflow                         |
-| Discord announcement     | `.github/workflows/discord-release-announcement.yml` | Preview and publish one idempotent product-aware release announcement     |
-| Contributor onboarding   | `.github/workflows/contributor-onboarding.yml`       | Accepted-contributor onboarding automation                                |
-| Contributor Hub          | `.github/workflows/contributor-hub.yml`              | Daily live issue-route freshness                                          |
-| Welcome                  | `.github/workflows/welcome.yml`                      | First-issue and first-contribution messages                               |
+| Workflow                  | Path                                                      | Purpose                                                                                   |
+| ------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| Build / test matrix       | `.github/workflows/ci.yml`                                | Path-aware docs or full matrix validation plus the required `CI Gate`                     |
+| Workspace E2E matrix      | `.github/workflows/workspace-e2e-matrix.yml`              | Cross-OS workspace lifecycle smoke; setup `--warm-deps`; cache/mirror ops                 |
+| Windows bridge E2E        | `.github/workflows/windows-bridge-e2e.yml`                | Native Windows bridge and lifecycle checks                                                |
+| E2E smoke                 | `.github/workflows/e2e-smoke.yml`                         | Focused bridge regression smoke                                                           |
+| Official generator smoke  | `.github/workflows/frontend-generator-smoke.yml`          | Contract-driven official-generator drift gate                                             |
+| Agent Framework matrix    | `.github/workflows/agent-framework-conformance.yml`       | Affected-family Linux PR gate plus manual twelve-lane release qualification and admission |
+| Agent Framework discovery | `.github/workflows/agent-framework-version-discovery.yml` | Weekly PyPI/NuGet candidate report; no commit, PR, or contract rewrite                    |
+| Model Gateway matrix      | `.github/workflows/model-gateway-qualification.yml`       | Three-OS generated-project and lifecycle qualification; manual fast mode stays on Linux |
+| Model Gateway discovery   | `.github/workflows/model-gateway-version-discovery.yml`   | Weekly npm/PyPI/GitHub candidate report; no baseline write, commit, or PR                 |
+| Security                  | `.github/workflows/security.yml`                          | Path-aware scanning plus the always-resolved `Security Gate`                              |
+| Manual npm release        | `.github/workflows/release-npm-manual.yml`                | Maintainer-only release gate and publish workflow                                         |
+| Discord announcement      | `.github/workflows/discord-release-announcement.yml`      | Preview and publish one idempotent product-aware release announcement                     |
+| Contributor onboarding    | `.github/workflows/contributor-onboarding.yml`            | Accepted-contributor onboarding automation                                                |
+| Contributor Hub           | `.github/workflows/contributor-hub.yml`                   | Daily live issue-route freshness                                                          |
+| Welcome                   | `.github/workflows/welcome.yml`                           | First-issue and first-contribution messages                                               |
 
 ## Agent Framework workflows
 
-Weekly `agent-framework-version-discovery` checks PyPI and NuGet, then stops at
+Weekly `agent-framework-version-discovery` checks PyPI, NuGet, and npm, then stops at
 a report and artifact. It does not commit, open a pull request, regenerate
-Create contracts, or write `release-admissions.v1.json`. A human pin update
-still has to pass `agent-framework-conformance` on Linux, macOS, and Windows
-for Python and .NET. That matrix compiles the nested `agents/primary` runtime,
-runs credentialless context-boundary tests, and records digest-bound evidence.
-It never sets Foundry credentials. Only a reviewed admission on the protected
+Create contracts, or write `release-admissions.v2.json`. A human pin update
+still has to pass the manual `full` mode of `agent-framework-conformance` on
+Linux, macOS, and Windows for every built-in adapter runtime. Pull requests run
+the faster Linux gate only for the affected Microsoft or OpenAI family; shared
+agent-framework surfaces select both, while documentation-only changes skip the
+specialized workflow. The full matrix compiles the nested `agents/primary`
+runtime, runs credentialless context-boundary tests, and records manifest-bound
+admission data plus semantic implementation provenance. Promotion requires the
+candidate source commit to equal the checked-out promotion commit. An
+implementation digest is audit evidence, not a runtime lock and not a manual
+maintenance requirement after every routine adapter edit.
+It never sets Foundry or OpenAI credentials. Only a reviewed admission on the protected
 version-update branch can promote a green candidate.
 
+OpenRouter AI Gateway kits are not part of the Agent Framework conformance
+matrix. They use a dedicated qualification workflow for generated-project
+install, tests, smoke, missing-key startup, Workspace Run, and Workspace
+Verify. Path-triggered runs and manual `full` mode qualify both adapters on
+Linux, macOS, and Windows. Manual `fast` mode is the only single-OS path.
+Weekly discovery reports newer stable sdk-core versions, with registry and
+GitHub agreement shown as a candidate diff. It does not write the baseline or
+open a pull request. See [AI Gateway](./model-gateways.md).
+
 The PR template at `.github/agent-framework-version-update.md` is for that
 human pin update. It is not opened by the weekly discovery workflow.
 
@@ -118,7 +136,7 @@ Validate or preview the current CLI announcement locally:
 npm --workspace workspai run check:release-announcement
 npm --workspace workspai run release:announcement -- \
   --product workspai-cli \
-  --tag v0.75.2 \
+  --tag v0.77.0 \
   --markdown-output /tmp/workspai-discord-announcement.md
 ```
 

package/docs/commands-reference.md

@@ -82,11 +82,13 @@ npx workspai change capsule validate --change <change-id> [--workspace <path>] [
 npx workspai change capsule export --change <change-id> --output <path> [--workspace <path>] [--json]
 npx workspai create project agent.microsoft.python <name> [--agent-name <name>] [--skip-git]
 npx workspai create project agent.microsoft.dotnet <name> [--agent-name <name>] [--skip-git]
+npx workspai create project gateway.openrouter.typescript <name> [--skip-git] [--json]
+npx workspai create project gateway.openrouter.python <name> [--skip-git] [--json]
 npx workspai agent bootstrap [--project <path>] [--for-agent <host>] [--no-live-inputs] [--strict] [--json]
 npx workspai agent framework list [--json]
-npx workspai agent framework plan --project <name> --runtime <python|dotnet> --name <agent> [--goal <goal-id>] [--workspace <path>] [--json]
-npx workspai agent framework attach --project <name> --runtime <python|dotnet> --name <agent> [-y] [--granted-by <identity>] [--workspace <path>] [--json]
-npx workspai agent framework apply --change <change-id> --project <name> --runtime <python|dotnet> [--workspace <path>] [--json]
+npx workspai agent framework plan --project <name> --runtime <python|dotnet|node> [--framework <id>] --name <agent> [--goal <goal-id>] [--workspace <path>] [--json]
+npx workspai agent framework attach --project <name> --runtime <python|dotnet|node> [--framework <id>] --name <agent> [-y] [--granted-by <identity>] [--workspace <path>] [--json]
+npx workspai agent framework apply --change <change-id> --project <name> --runtime <python|dotnet|node> [--framework <id>] [--workspace <path>] [--json]
 ```
 
 Recommended CI:
@@ -275,16 +277,25 @@ Blocked receipts exit `2`; strict mode also maps degraded evidence to exit `2`.
 See [Canonical-first agent entry](./agent-entry.md).
 
 `agent framework` is the governed bridge between Workspai evidence and an
-agent runtime. `list` exposes only exact release-admitted baselines: Python
-`1.18.0` and .NET `1.21.0` in this CLI version. `plan` creates or reuses a
-scoped Goal, begins a Proof-Carrying Change, and attaches a hash-bound file
-plan without writing project files. `attach` shows that plan and requires an
+agent runtime. `list` exposes every built-in adapter and its release-admission
+state. In this CLI version Microsoft Python `1.18.0` and .NET `1.21.0` remain
+`preview`. OpenAI Agents SDK Python `0.22.2` and TypeScript `0.18.0` are
+labeled `stable`. Create and Attach require the reviewed v2 release inventory,
+whose manifest, framework baseline, runtime, and platform claims were promoted
+from the Linux, macOS, and Windows release matrix. Semantic implementation
+digests remain audit provenance rather than runtime authorization. `plan`
+creates or reuses a scoped Goal, begins a Proof-Carrying Change, and
+attaches a hash-bound file plan without writing project files. `--runtime`
+selects `python`, `dotnet`, or `node`. `--framework` selects the independent
+framework id when more than one admitted adapter shares that runtime.
+`attach` shows that plan and requires an
 interactive confirmation or explicit `--yes` before granting the filesystem
 effect and writing an isolated `agents/<name>` directory. `create project
 agent.microsoft.python|dotnet` uses the same admitted lifecycle for a new
 project: it registers the project, plans against a Model baseline, writes the
 nested runtime, then re-observes Model/Graph before it claims Intelligence is
-sealed. Dependency installation, credentials, generated-code execution, and
+sealed. `create project agent.openai.python|typescript` uses the same admitted
+lifecycle. Dependency installation, credentials, generated-code execution, and
 model provider calls are never implied by that approval. `apply` is the
 automation counterpart for a plan that was separately authorized with
 `change authorize`. Any adapter, version, manifest, runtime, or platform drift

package/docs/create-planner-capabilities.md

@@ -22,6 +22,7 @@ Native create is reserved for Workspai-owned kits with deterministic contracts:
 - Spring Boot
 - ASP.NET Core Web API
 - Rust / Axum
+- OpenRouter AI Gateway (TypeScript and Python)
 
 These kits can be exposed through `workspai create project` because Workspai can
 create the project and immediately produce the expected `.workspai` metadata,

package/docs/creating-workspaces-and-projects.md

@@ -16,9 +16,9 @@ For a compact list of command syntax, see
 A **workspace** is the shared home for related projects, rules, and saved
 Workspai reports.
 
-A **project** is an application, service, or governed agent, such as a FastAPI
-API, Go service, Spring Boot service, .NET API, frontend application, or
-Microsoft Agent Framework entrypoint.
+A **project** is an application, service, governed agent, or model gateway, such as a FastAPI
+API, Go service, Spring Boot service, .NET API, frontend application,
+Microsoft Agent Framework entrypoint, or OpenRouter AI Gateway.
 
 The canonical commands are:
 
@@ -42,6 +42,7 @@ does not have exactly the same behavior.
 | Turn the current folder into a workspace before creating        | `npx workspai create project gofiber.standard api --create-workspace --yes` |
 | Create a project without workspace management                   | `npx workspai create project gofiber.standard api --no-workspace --yes`     |
 | Create a governed Microsoft Agent Framework project             | `npx workspai create project agent.microsoft.python support-agent`          |
+| Create a server-owned OpenRouter AI Gateway                     | `npx workspai create project gateway.openrouter.typescript model-gateway`   |
 | Preview a supported create plan                                 | `npx workspai create project frontend.nextjs web --dry-run`                 |
 
 # Creating a workspace
@@ -394,9 +395,11 @@ project metadata and performs the selected workspace registration.
 | ------------------------ | ------- | --------------- | ------ |
 | `agent.microsoft.python` | Python  | `agent-framework-core` `1.18.0`, Foundry `1.13.0`, `azure-identity` `1.25.3` | Isolated `agents/<instance>/` with `pyproject.toml`, credentialless `unittest`, and `.env.example` |
 | `agent.microsoft.dotnet` | .NET    | `Microsoft.Agents.AI` `1.21.0`, Foundry `1.21.0-preview.260911.1` | Isolated `agents/<instance>/` with the executable project plus a dedicated test project |
+| `agent.openai.python` | Python | `openai-agents` `0.22.2` | Isolated `agents/<instance>/` with pip-editable `pyproject.toml`, credentialless `unittest`, and `.env.example` |
+| `agent.openai.typescript` | Node.js | `@openai/agents` `0.18.0`, `zod` `4.6.5` | Isolated `agents/<instance>/` with `package.json`, credentialless `node:test`, and `.env.example` |
 
-Interactive `workspai create` shows these kits under **AI Agent** only after
-release admission. Agent kits require Workspace governance and therefore do not
+Interactive `workspai create` shows these kits under **AI Agent** after
+reviewed release admission. Agent kits require Workspace governance and therefore do not
 accept `--no-workspace`. Optional `--agent-name` names the instance directory
 (default `primary`). They do not install dependencies, call a model, or store
 credentials. Exact versions are promoted only after the full Linux, macOS, and
@@ -416,6 +419,21 @@ npx workspai change verify --change <change-id> --json
 independent proof for this scaffold. See
 [Agent Framework Adapter Contract](./agent-framework-adapters.md).
 
+## AI Gateway kits
+
+| Kit | Runtime | Tested baseline | Layout |
+| --- | --- | --- | --- |
+| `gateway.openrouter.typescript` | Node.js | `@openrouter/sdk` `1.3.11`, TypeScript `5.9.3`, `@types/node` `22.20.3` | Server-owned OpenRouter Client SDK starter with `gateway.policy.json`, credentialless `node:test`, and `.env.example` |
+| `gateway.openrouter.python` | Python | `openrouter` `1.2.11` | Server-owned OpenRouter Client SDK starter with `gateway.policy.json`, credentialless `unittest`, and `.env.example` |
+
+Interactive `workspai create` shows these kits under **AI Gateway** with the
+hint **Unified model access and routing**. A model identifier is runtime
+configuration, not a kit. Create does not install dependencies, call a model,
+or store credentials. Attach is not supported for Gateway in this release.
+The official Go Client SDK remains beta (`v0.8.11` on
+2026-09-21) and is not admitted. See
+[AI Gateway](./model-gateways.md).
+
 ## Desktop, extension, and additional backend generators
 
 | Category  | Project           | Kit                | Creation owner                        |
@@ -426,10 +444,11 @@ independent proof for this scaffold. See
 | Desktop   | Electron Forge    | `desktop.electron` | create-electron-app                   |
 | Extension | VS Code Extension | `extension.vscode` | generator-code                        |
 
-Every generated project receives a canonical `kind` and `category`. The five
-user-facing creation categories are `backend`, `frontend`, `desktop`, `agent`, and `extension`;
-they remain visible in the Workspace Model and Knowledge Graph so consumers do
-not have to guess a project’s role from its runtime.
+Every generated project receives a canonical `kind` and `category`. The
+user-facing creation categories are `backend`, `frontend`, `desktop`, `agent`,
+`gateway`, and `extension`; they remain visible in the Workspace Model and
+Knowledge Graph so consumers do not have to guess a project’s role from its
+runtime.
 
 Official generators may download packages and therefore need network access.
 Each available integration requests the upstream latest stable channel rather

package/docs/doctor-command.md

@@ -775,10 +775,15 @@ These fields are designed for release gates and extension timeline cards that mu
 - Supports Workspai, legacy RapidKit, and non-Workspai projects when project metadata is missing.
 - Evidence: `.workspai/reports/doctor-project-last-run.json`.
 - `--fix`, `--plan`, and `--apply` apply only project-scoped fixes.
-- Governed Microsoft Agent Framework projects keep `kind`/`framework` as `agent` /
-  `microsoft-agent-framework`. Doctor discovers nested environment examples and
-  dependency manifests under `agents/primary` and aims Python/`uv` or .NET
-  repair commands at that runtime, not at a phantom project-root manifest.
+- Governed Microsoft Agent Framework and OpenAI Agents SDK projects keep
+  `kind` as `agent`. Microsoft retains `microsoft-agent-framework`; OpenAI
+  retains `openai-agents`. Doctor discovers nested environment examples and
+  dependency manifests under `agents/primary` and aims Python/`uv`, Node
+  `npm --prefix`, or .NET repair commands at that runtime, not at a phantom
+  project-root manifest.
+- OpenRouter AI Gateway projects keep `kind` as `gateway` and `framework` as
+  `openrouter`. Doctor uses the project-root Node or Python runtime, not the
+  Agent Framework nested layout.
 
 ## Project JSON fields (AI/automation)