workspai 0.75.2 → 0.77.0

package/docs/model-gateways.md

@@ -0,0 +1,204 @@
+# AI Gateway
+
+AI Gateway is a first-class Workspai project category for unified model access
+and routing. It is not an Agent Framework.
+
+## Why Gateway is not Agent Framework
+
+Agent Framework owns agent loops, tools, handoffs, state, and orchestration.
+AI Gateway owns model and provider access, routing preferences, fallbacks,
+privacy policy, and normalized transport behavior.
+
+A model identifier is runtime configuration, not a project kit. Workspai owns
+project generation, governance, context, lifecycle, verification, workspace
+integration, and proof. OpenRouter owns provider and model routing. Generated
+projects do not reimplement OpenRouter's routing algorithms.
+
+Future agent-to-gateway composition should consume the generated Model Gateway
+port. Do not copy these templates into an Agent Framework kit.
+
+## Current kits
+
+These kits ship as source-ready. That is not Workspai release admission and
+does not label them `stable` or `qualified`. SDK `1.x` stability is an upstream
+classification, not a Workspai release gate.
+
+| Kit | Runtime | Official Client SDK | Reviewed |
+| --- | --- | --- | --- |
+| `gateway.openrouter.typescript` | Node.js `>=20` | `@openrouter/sdk` `1.3.11` | 2026-09-21 |
+| `gateway.openrouter.python` | Python `>=3.10` | `openrouter` `1.2.11` | 2026-09-21 |
+
+Aliases: `openrouter.typescript`, `gateway.openrouter.ts`, `openrouter-typescript`,
+and the matching Python aliases. Bare `openrouter` is not an alias.
+
+Interactive Create shows **AI Gateway** with the hint **Unified model access
+and routing** after at least one gateway kit is registered. Labels are:
+
+- `AI Gateway · OpenRouter · TypeScript`
+- `AI Gateway · OpenRouter · Python`
+
+```bash
+npx workspai create project gateway.openrouter.typescript <name>
+npx workspai create project gateway.openrouter.python <name>
+```
+
+Create does not install dependencies, call a model, or write credentials.
+
+Attach is not supported for AI Gateway in this release. Do not use
+`agent framework attach` or any gateway-specific attach command. Adopt an
+existing OpenRouter project only by creating a new gateway kit or by adding
+the generated starter beside user-owned code. Repeated Create is not Attach.
+
+## Version upgrades
+
+Exact SDK pins live only in
+[`version-baselines.v1.json`](../src/model-gateways/version-baselines.v1.json).
+`releaseChannel: stable` means the upstream SDK release is stable. It does not
+mean the Workspai adapter passed Linux, macOS, and Windows qualification.
+
+The supported upgrade path is read-only until a human reviews the proposal:
+
+```text
+discover → propose → review → qualify → merge
+```
+
+```bash
+npm --workspace workspai run propose:model-gateway:versions -- \
+  --baseline src/model-gateways/version-baselines.v1.json \
+  --report test-results/model-gateway-version-discovery.json
+```
+
+The command does not commit, push, open a pull request, or write the baseline
+unless `--write` is passed after the on-disk file matches the validated
+in-memory document and every candidate agrees across registry and GitHub.
+A normal SDK upgrade should not require editing generator source when the
+upstream contract is compatible. Three-OS qualification must be green on the
+same commit before a Workspai release can present these kits as qualified.
+
+## Intentionally unsupported languages
+
+The official Go SDK (`github.com/OpenRouterTeam/go-sdk`) was evaluated on
+2026-09-21. The upstream README classifies the current `0.x` line as beta and
+warns that breaking changes may ship in minor releases. proxy.golang.org
+reported `v0.8.11`. Go is excluded from the stable Create surface until
+upstream classifies a release line as stable.
+
+The OpenRouter Agent SDK (`@openrouter/agent`) belongs to the agent-runtime
+dimension. It is not used by AI Gateway kits and is not added as
+`agent.openrouter.typescript` in this family.
+
+## Configuration
+
+Required environment:
+
+- `OPENROUTER_API_KEY` — server-side only
+- `OPENROUTER_MODEL` — chosen by the operator; Workspai does not default a
+  billable model
+
+Optional attribution maps to the official SDK fields:
+
+- TypeScript: `httpReferer`, `appTitle` via `OPENROUTER_HTTP_REFERER` and
+  `OPENROUTER_APP_TITLE`
+- Python: `http_referer`, `x_open_router_title` via `OPENROUTER_HTTP_REFERER`
+  and `OPENROUTER_X_OPEN_ROUTER_TITLE`
+
+Routing and privacy policy live in source-controlled `gateway.policy.json`.
+Field names match the pinned SDK for that language. Unknown fields are rejected
+fail-closed in both languages. Supported controls:
+
+| Official field | TypeScript policy | Python policy | Validation |
+| --- | --- | --- | --- |
+| model fallbacks | `models` | `models` | unique non-empty strings; must not repeat `OPENROUTER_MODEL` |
+| `allowFallbacks` | `allowFallbacks` | `allow_fallbacks` | boolean when present |
+| `order` / `only` / `ignore` | same camelCase | same snake_case | unique non-empty strings; `only`∩`ignore` empty; `order` must not include ignored providers |
+| `sort` | string or `{ by, partition }` | string or `{ by, partition }` | `price`/`throughput`/`latency`/`exacto`; `partition` is `model` or `none` |
+| `quantizations` | camelCase list | snake_case list | pinned SDK enum values |
+| `requireParameters` | `requireParameters` | `require_parameters` | boolean when present |
+| `zdr` | `zdr` | `zdr` | boolean; cannot combine with `dataCollection`/`data_collection` `allow` |
+| `dataCollection` | `dataCollection` | `data_collection` | `allow` or `deny` |
+| `enforceDistillableText` | `enforceDistillableText` | `enforce_distillable_text` | boolean when present; both pinned SDKs expose this field |
+| `maxPrice` | `maxPrice` | `max_price` | object with `prompt`/`completion`/`request`/`image`/`audio` as non-negative numeric strings that remain finite after numeric interpretation |
+| `preferredMinThroughput` | number or `{ p50, p75, p90, p99 }` | same | finite non-negative numbers |
+| `preferredMaxLatency` | number or `{ p50, p75, p90, p99 }` | same | finite non-negative numbers |
+| timeout | `timeoutMs` | `timeout_ms` | integer 1–600000; env overrides with a digit string |
+| attribution | `httpReferer`, `appTitle` | `http_referer`, `x_open_router_title` | strings when present |
+
+`exacto` is part of the pinned SDK `ProviderSort` enums, not a Workspai extension.
+Malformed JSON and wrong types raise `GatewayConfigurationError` before SDK
+construction. Contradictory policy, including ZDR combined with
+`dataCollection: "allow"`, fails before a network request.
+
+Omitted privacy or routing fields leave OpenRouter upstream defaults in
+effect. The SDKs document `dataCollection` / `data_collection` default as
+`allow` when unset. Application-side retries are set to strategy `none` so they
+cannot duplicate billable requests. OpenRouter may still apply provider
+fallbacks when `allowFallbacks` / `allow_fallbacks` is not `false`.
+
+Capabilities such as tools, JSON schema, structured output, images, audio, and
+embeddings vary by model and provider. These starters only claim chat
+generation and streaming.
+
+## Security
+
+- Never commit, log, or serialize API keys.
+- Generated clients are server-side only. Do not expose `OPENROUTER_API_KEY`
+  through browser bundles or frontend environment prefixes such as `VITE_` or
+  `NEXT_PUBLIC_`.
+- Diagnostics redact Authorization headers, API keys, URL secrets, and request
+  bodies.
+- TLS verification is not disabled.
+- Telemetry and prompt recording are not added.
+
+## Lifecycle
+
+After local install, documented commands are:
+
+TypeScript: `npm install`, `npm test`, `npm run typecheck`, `npm run build`,
+`npm run smoke`, `npm start`.
+
+Python: create a virtualenv, `python -m pip install -e .`, `python -m compileall .`,
+`python -m unittest discover -s tests`, `python main.py --smoke`, `python main.py`.
+
+Workspace Run uses those same manifests and the generated project's declared
+polyglot unit commands. Stage commands, including `&&` chains and a multi-step
+`start`, run as argv. They are not passed to a shell, so an absolute interpreter
+path cannot be expanded by `/bin/sh`. `test` and `--smoke` inject a fake
+transport. They do not require a live `OPENROUTER_API_KEY`.
+
+Streaming uses the official Client SDK event stream. Opening and iterating the
+stream are both normalized: configuration errors stay configuration errors,
+timeouts and caller aborts stay recognizable, and other failures become
+`GatewayUpstreamError` with redacted messages and preserved status / request id /
+retry-after when the SDK exposes them. Cleanup is once-only and prefers, in
+order: async iterator `return()` / generator `close()`, then SDK `close()`, then
+SDK `cancel()`. A cleanup failure does not replace the primary error or convert
+a successful completion into an error.
+
+The TypeScript starter forwards `AbortSignal` through `chat.send` options,
+including an already-aborted signal. Pinned `@openrouter/sdk` `1.3.11`
+`EventStream` extends `ReadableStream` and does not expose a dedicated `close()`.
+Cancellation is `ReadableStream` async-iterator `return()` → `cancel()`. If the
+stream has already errored, `cancel()` may be a no-op; the gateway still drops
+its own reference and remains usable for a later request. The Python starter
+closes the SDK iterator first (`EventStream.generator.close()`), which is the
+consumer `generator.close()` path. Python does not expose `AbortSignal`.
+Application-side retries stay disabled. Timeouts use SDK `timeoutMs` /
+`timeout_ms`. An empty successful completion returns an empty string.
+
+Exact pins live in
+[`version-baselines.v1.json`](../src/model-gateways/version-baselines.v1.json).
+Do not copy versions into unrelated files.
+
+## Qualification boundary
+
+Workspai source readiness is not release qualification. These kits are not
+described as `stable`, `release-ready`, `admitted`, or `qualified` until Linux,
+macOS, and Windows CI prove generated-project installation and lifecycle on the
+same commit SHA, and a later admission change records that evidence. The
+dedicated workflow is `.github/workflows/model-gateway-qualification.yml`.
+Path-triggered runs and manual `full` mode each qualify both the TypeScript and
+Python OpenRouter adapters on Linux, macOS, and Windows. Manual `fast` mode
+stays on Linux. There is no unused kit axis. Discovery is
+`.github/workflows/model-gateway-version-discovery.yml`. Its job summary shows
+the sdk-core candidate diff when registry and GitHub agree. A green job that
+skipped installation or lifecycle is not qualified.

package/docs/native-kit-baselines.md

@@ -12,9 +12,11 @@ native kits:
 This policy does not cover FastAPI or NestJS kits owned by the RapidKit Python
 engine. It also does not cover generators delegated to an upstream official
 CLI, such as Next.js, Astro, Angular, Vue, Svelte, Nuxt, or React Native.
-Governed Microsoft Agent Framework kits are versioned separately through the
+Governed Microsoft Agent Framework and OpenAI Agents SDK kits are versioned
+separately through the
 [Agent Framework Adapter Contract](./agent-framework-adapters.md); they are
-not native HTTP service generators.
+not native HTTP service generators. OpenRouter AI Gateway kits are versioned
+through [AI Gateway](./model-gateways.md) and are not Agent Framework kits.
 
 ## Current tested baseline
 

package/docs/workspace-run.md

@@ -52,7 +52,9 @@ Microsoft Agent Framework projects keep their executable manifest under
 `agents/<instance>/`. Workspace Run treats that nested `pyproject.toml` or
 `.csproj` as its own unit (`python3 -m compileall .`,
 `python3 -m unittest discover -s tests`, `python3 main.py`, or the matching
-.NET commands). An empty legacy root manifest is ignored only when it still
+.NET commands). A Python unit with `main.py` uses `compileall` even when
+`pyproject.toml` declares `[build-system]`; `python -m build` remains only for
+packaging projects that have no agent entrypoint. An empty legacy root manifest is ignored only when it still
 matches the exact older Workspai shell and a real `agents/primary` runtime
 exists. Any user edit restores the root as an independent unit.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workspai",
-  "version": "0.75.2",
+  "version": "0.77.0",
   "type": "module",
   "description": "Open-source workspace intelligence CLI for software systems: create, adopt, govern, verify, and align polyglot workspaces for humans, CI, IDEs, and AI agents.",
   "keywords": [
@@ -115,9 +115,13 @@
     "test:runtime-contract": "node scripts/runtime-acceptance-matrix.mjs --contract-only",
     "test:agent-framework:python": "tsx scripts/smoke-microsoft-agent-framework-adapter.ts --runtime python",
     "test:agent-framework:dotnet": "tsx scripts/smoke-microsoft-agent-framework-adapter.ts --runtime dotnet",
+    "test:agent-framework:openai:python": "tsx scripts/smoke-openai-agents-adapter.ts --runtime python",
+    "test:agent-framework:openai:typescript": "tsx scripts/smoke-openai-agents-adapter.ts --runtime typescript",
     "verify:agent-framework:matrix": "tsx scripts/verify-agent-framework-conformance.ts --reports test-results/agent-framework-conformance",
     "discover:agent-framework:versions": "tsx scripts/discover-agent-framework-versions.ts",
     "propose:agent-framework:versions": "tsx scripts/propose-agent-framework-version-update.ts",
+    "discover:model-gateway:versions": "tsx scripts/propose-model-gateway-version-update.ts",
+    "propose:model-gateway:versions": "tsx scripts/propose-model-gateway-version-update.ts",
     "promote:agent-framework:admission": "tsx scripts/promote-agent-framework-release-admission.ts",
     "prepush:test:runtime-contract": "node scripts/run-cached-prepush-gate.mjs runtime-contract",
     "test:runtime-matrix:full": "node scripts/runtime-acceptance-matrix.mjs --full",

package/scripts/enterprise-package-smoke.mjs

@@ -9,6 +9,7 @@ import process from 'node:process';
 const repoRoot = process.cwd();
 const cliPath = path.join(repoRoot, 'dist', 'index.js');
 const isolatedHome = fs.mkdtempSync(path.join(os.tmpdir(), 'workspai-enterprise-home-'));
+let releaseAdmittedAdapterIds = new Set();
 
 process.on('exit', () => {
   fs.rmSync(isolatedHome, { recursive: true, force: true });
@@ -348,12 +349,43 @@ function assertCliContracts() {
   }
 
   const frameworks = parseTrailingJson(runCli(['agent', 'framework', 'list', '--json']));
+  if (frameworks.schemaVersion !== 'workspai.agent-framework-list.v1') {
+    fail(`unexpected agent framework list schema: ${frameworks.schemaVersion}`);
+  }
+  const adapters = Array.isArray(frameworks.adapters) ? frameworks.adapters : [];
+  const admittedIds = adapters
+    .filter((adapter) => adapter.status === 'admitted')
+    .map((adapter) => adapter.id)
+    .sort();
+  const expectedAdapterIds = [
+    'microsoft-agent-framework-dotnet',
+    'microsoft-agent-framework-python',
+    'openai-agents-python',
+    'openai-agents-typescript',
+  ];
   if (
-    frameworks.schemaVersion !== 'workspai.agent-framework-list.v1' ||
-    frameworks.adapters?.length !== 2 ||
-    frameworks.adapters.some((adapter) => adapter.status !== 'admitted')
+    admittedIds.length !== 0 &&
+    JSON.stringify(admittedIds) !== JSON.stringify(expectedAdapterIds)
   ) {
-    fail('published CLI does not expose the two exact release-admitted framework adapters');
+    fail(
+      `published CLI does not expose the exact release-admitted framework adapters (admitted: ${
+        admittedIds.join(', ') || 'none'
+      })`
+    );
+  }
+  releaseAdmittedAdapterIds = new Set(admittedIds);
+  for (const openaiId of ['openai-agents-python', 'openai-agents-typescript']) {
+    const openai = adapters.find((adapter) => adapter.id === openaiId);
+    if (!openai) {
+      fail(`published CLI is missing implemented OpenAI adapter ${openaiId}`);
+    }
+    if (openai.stability !== 'stable') {
+      fail(
+        `${openaiId} must be labeled stable after the digest-changing promotion (observed: ${
+          openai.stability ?? 'missing'
+        })`
+      );
+    }
   }
 
   log(`verified CLI contract surfaces for v${version.version}`);
@@ -390,6 +422,7 @@ function smokeCreateAgentFrameworkKits() {
     {
       kit: 'agent.microsoft.python',
       name: 'python-agent',
+      expectCreate: releaseAdmittedAdapterIds.has('microsoft-agent-framework-python'),
       expectedFiles: [
         'README.md',
         '.workspai/project.json',
@@ -404,6 +437,7 @@ function smokeCreateAgentFrameworkKits() {
     {
       kit: 'agent.microsoft.dotnet',
       name: 'dotnet-agent',
+      expectCreate: releaseAdmittedAdapterIds.has('microsoft-agent-framework-dotnet'),
       expectedFiles: [
         'README.md',
         '.workspai/project.json',
@@ -417,6 +451,41 @@ function smokeCreateAgentFrameworkKits() {
         'agents/primary/README.md',
       ],
     },
+    {
+      kit: 'agent.openai.python',
+      name: 'openai-python-agent',
+      expectCreate: releaseAdmittedAdapterIds.has('openai-agents-python'),
+      expectedFiles: [
+        'README.md',
+        '.workspai/project.json',
+        '.workspai/agent-frameworks/openai-agents-python/primary.json',
+        'agents/primary/main.py',
+        'agents/primary/workspai_context.py',
+        'agents/primary/agent.py',
+        'agents/primary/pyproject.toml',
+        'agents/primary/tests/test_context.py',
+        'agents/primary/.env.example',
+        'agents/primary/README.md',
+      ],
+    },
+    {
+      kit: 'agent.openai.typescript',
+      name: 'openai-typescript-agent',
+      expectCreate: releaseAdmittedAdapterIds.has('openai-agents-typescript'),
+      expectedFiles: [
+        'README.md',
+        '.workspai/project.json',
+        '.workspai/agent-frameworks/openai-agents-typescript/primary.json',
+        'agents/primary/src/main.ts',
+        'agents/primary/src/workspai-context.ts',
+        'agents/primary/src/agent.ts',
+        'agents/primary/package.json',
+        'agents/primary/tsconfig.json',
+        'agents/primary/tests/context.test.ts',
+        'agents/primary/.env.example',
+        'agents/primary/README.md',
+      ],
+    },
   ];
   try {
     for (const scenario of scenarios) {
@@ -430,6 +499,22 @@ function smokeCreateAgentFrameworkKits() {
           stdio: ['ignore', 'pipe', 'pipe'],
         }
       );
+      const combined = `${result.stdout}\n${result.stderr}`;
+      if (scenario.expectCreate === false) {
+        if (result.status === 0) {
+          fail(`${scenario.kit} create succeeded before the stable digest was release-admitted`);
+        }
+        if (
+          !/not release-admitted|adapter (?:manifest|implementation) changed after release admission/i.test(
+            combined
+          )
+        ) {
+          fail(
+            `${scenario.kit} failed closed without an admission blocker\n${result.stdout}\n${result.stderr}`
+          );
+        }
+        continue;
+      }
       if (result.status !== 0) {
         fail(
           `${scenario.kit} governed create failed with exit ${result.status}\n${result.stdout}\n${result.stderr}`
@@ -437,8 +522,16 @@ function smokeCreateAgentFrameworkKits() {
       }
       assertGeneratedProject(path.join(workspacePath, scenario.name), scenario.expectedFiles);
     }
+    const admittedCreates = scenarios.filter((scenario) => scenario.expectCreate);
     const ownershipRoot = path.join(workspacePath, '.workspai', 'agent-frameworks', 'ownership');
-    if (!fs.existsSync(ownershipRoot)) fail('agent kit smoke did not record ownership receipts');
+    const recordedOwnership = fs.existsSync(ownershipRoot);
+    if (admittedCreates.length === 0) {
+      if (recordedOwnership) {
+        fail('agent kit smoke recorded ownership receipts without a release-admitted create');
+      }
+    } else if (!recordedOwnership) {
+      fail('agent kit smoke did not record ownership receipts');
+    }
   } finally {
     fs.rmSync(tempDir, { recursive: true, force: true });
   }
@@ -626,10 +719,112 @@ for (const relativePath of [
   assertFile(relativePath);
 }
 
+function smokeCreateOpenRouterGatewayKits() {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'workspai-gateway-kit-smoke-'));
+  const workspaceName = 'gateway-kit-workspace';
+  const workspacePath = path.join(tempDir, workspaceName);
+  const createWorkspace = spawnSync(
+    process.execPath,
+    [
+      cliPath,
+      'create',
+      'workspace',
+      workspaceName,
+      '--output',
+      tempDir,
+      '--profile',
+      'minimal',
+      '--skip-python-engine',
+      '--skip-git',
+      '--yes',
+    ],
+    { cwd: tempDir, encoding: 'utf8', env: cliEnv(), stdio: ['ignore', 'pipe', 'pipe'] }
+  );
+  if (createWorkspace.status !== 0) {
+    fail(
+      `gateway kit workspace creation failed with exit ${createWorkspace.status}\n${createWorkspace.stdout}\n${createWorkspace.stderr}`
+    );
+  }
+
+  const scenarios = [
+    {
+      kit: 'gateway.openrouter.typescript',
+      name: 'openrouter-ts-gateway',
+      expectedFiles: [
+        'README.md',
+        '.env.example',
+        '.gitignore',
+        'gateway.policy.json',
+        'package.json',
+        'tsconfig.json',
+        'src/port.ts',
+        'src/config.ts',
+        'src/openrouter-gateway.ts',
+        'src/main.ts',
+        'tests/gateway.test.ts',
+        '.workspai/project.json',
+      ],
+    },
+    {
+      kit: 'gateway.openrouter.python',
+      name: 'openrouter-py-gateway',
+      expectedFiles: [
+        'README.md',
+        '.env.example',
+        '.gitignore',
+        'gateway.policy.json',
+        'pyproject.toml',
+        'main.py',
+        'src/model_gateway/port.py',
+        'src/model_gateway/config.py',
+        'src/model_gateway/gateway.py',
+        'src/model_gateway/main.py',
+        'tests/test_gateway.py',
+        '.workspai/project.json',
+      ],
+    },
+  ];
+  try {
+    for (const scenario of scenarios) {
+      const result = spawnSync(
+        process.execPath,
+        [cliPath, 'create', 'project', scenario.kit, scenario.name, '--skip-git', '--yes'],
+        {
+          cwd: workspacePath,
+          encoding: 'utf8',
+          env: cliEnv(),
+          stdio: ['ignore', 'pipe', 'pipe'],
+        }
+      );
+      if (result.status !== 0) {
+        fail(
+          `${scenario.kit} create failed with exit ${result.status}\n${result.stdout}\n${result.stderr}`
+        );
+      }
+      const combined = `${result.stdout}\n${result.stderr}`;
+      if (/openrouter\.ai|chat\.completions|Authorization: Bearer/i.test(combined)) {
+        fail(`${scenario.kit} create output looks like a live model call\n${combined}`);
+      }
+      assertGeneratedProject(path.join(workspacePath, scenario.name), scenario.expectedFiles);
+      const envExample = fs.readFileSync(
+        path.join(workspacePath, scenario.name, '.env.example'),
+        'utf8'
+      );
+      if (/sk-or-[A-Za-z0-9]/.test(envExample) || /OPENROUTER_API_KEY=.+/.test(envExample)) {
+        fail(`${scenario.kit} .env.example must not contain a credential value`);
+      }
+    }
+    log(`verified ${scenarios.length} model gateway create scenarios`);
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
 assertPackContents();
 assertCliContracts();
 smokeCreateNpmBackedKits();
 smokeCreateAgentFrameworkKits();
+smokeCreateOpenRouterGatewayKits();
 smokeCreateOfflineFallbackKits();
 
 log('enterprise package smoke passed');

package/dist/analyze-6UEBC5OJ.js

@@ -1 +0,0 @@
-export{b as printAnalyzeReport,a as runAnalyze}from'./chunk-K52IQX3J.js';

package/dist/autopilot-release-H5TO6NYY.js

@@ -1 +0,0 @@
-export{b as AUTOPILOT_RELEASE_ALIAS_FILENAME,a as AUTOPILOT_RELEASE_LAST_RUN_FILENAME,c as runAutopilotRelease}from'./chunk-EP7SUMAX.js';

package/dist/capabilities-command-VK3LQLP2.js

@@ -1 +0,0 @@
-export{b as runDoctorCapabilities}from'./chunk-JKAAKE4Z.js';