@x-otto/plugin-otto-wire-protocols 0.1.0-alpha.14

package/README.md

@@ -0,0 +1,112 @@
+# @x-otto/plugin-otto-wire-protocols
+
+> Standard wire protocol implementations for the otto provider system.
+
+Provides three standard wire protocol implementations that were physically migrated out of the framework core: `anthropic-messages`, `openai-responses`, and `openai-completions`. Any declarative or code-based provider plugin that declares one of these `wireApi` values uses this plugin at runtime.
+
+## How it works
+
+This is a **code-based protocol plugin**. It registers three `wireProtocols` factories via `definePlugin`:
+
+- **`anthropic-messages`** — Wraps `createAnthropicProvider` for Claude API compatibility (Anthropic SDK format).
+- **`openai-responses`** — Wraps `createOpenAIResponsesProvider` for the OpenAI Responses API format.
+- **`openai-completions`** — Wraps `createOpenAICompletionsProvider` for the OpenAI Completions/Chat Completions API format.
+
+Each factory accepts a `WireProtocolFactoryInput` with `resolveAuth`, `resolveBaseUrl`, headers, and customization callbacks. Provider plugins (like `plugin-anthropic`, `plugin-deepseek`) reference these protocols by name rather than embedding protocol logic.
+
+This plugin is a **required peer dependency** of any provider plugin that uses the declarative `wireApi` or code-based `getWireProtocol` patterns.
+
+## Installation
+
+```bash
+otto extension install wire-protocols
+```
+
+All three protocols report cache token support through `meta.reportsCacheTokens`.
+
+## Standalone installation (non-CLI hosts, e.g. desktop apps)
+
+This plugin is published standalone to npm so hosts that depend only on `@x-otto/coding`
+(not the full `@x-otto/cli`, which pulls in ink/react/zustand/yoga-layout and other
+terminal-UI dependencies) can install it directly:
+
+```bash
+npm install @x-otto/plugin-otto-wire-protocols
+```
+
+Then pass its installed directory's **parent** directory to `AppOptions.pluginBundledDirs`
+(the same mechanism `@x-otto/cli` uses for its own `dist/bundled-extensions/`):
+
+```ts
+import { createApp } from '@x-otto/coding'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// import.meta.resolve gives the installed package's entry file; its grandparent
+// directory (node_modules/@x-otto/) is what discoverPlugins expects as bundledDirs —
+// it scans that directory's immediate children for otto-plugin.json manifests.
+const pkgEntry = fileURLToPath(import.meta.resolve('@x-otto/plugin-otto-wire-protocols'))
+const bundledDir = dirname(dirname(pkgEntry)) // .../node_modules/@x-otto
+
+const app = createApp({
+  // ...other options
+  pluginBundledDirs: [bundledDir],
+})
+```
+
+Plugins discovered through `pluginBundledDirs` get `scope: 'bundled'`, which
+auto-grants declared high-risk capabilities (this plugin declares `wire-protocol`) —
+same trust semantics as the CLI's own bundled extensions (RFC-341 M9): the host
+distributing the plugin is implicitly trusted by the user who installed the host.
+
+### Known deployment gap: prebuilt artifact freshness check fails after a standalone publish
+
+**Status as of the first standalone publish (2026-09, alpha.14): this is a known,
+unfixed gap in the release pipeline — verified against a real `pnpm pack` tarball,
+not a hypothetical.** A fresh `npm install @x-otto/plugin-otto-wire-protocols`
+(no extra copy step) currently makes the *first* load recompile instead of using the
+prebuilt `plugin-dist/plugin.cjs`, and that recompile fails unless `@anthropic-ai/sdk`
+is also resolvable (it is a normal `dependencies` entry, so `npm install` does bring
+it in as a sibling in `node_modules` — but bare/isolated environments without a full
+`npm install`, e.g. hand-built sanity checks, will see `Could not resolve
+"@anthropic-ai/sdk"`).
+
+Root cause: the freshness check (`isArtifactMetaCurrent` in `@x-otto/coding`)
+recomputes a source hash from whatever `.ts`/`.json` files currently exist in the
+plugin directory. `plugin-dist/meta.json`'s stored hash is computed at `pnpm build`
+time **against the monorepo source directory**, which includes `tests/` and
+`tsconfig.json`. The published npm package (filtered by `package.json`'s `files`
+field) does not include those — so the two hashes structurally can never match,
+regardless of how carefully the tarball is built. This is not specific to a copy
+step; it reproduces from a plain `pnpm pack` → extract → load with zero manual
+copying.
+
+If your `npm install` also resolves `@anthropic-ai/sdk` normally (the common case —
+npm's own dependency resolution handles this), the one-time recompile succeeds
+silently and you will not notice this gap; it only surfaces as a hard failure in
+constrained/offline environments. Either way it costs an unnecessary recompile on
+first load.
+
+**Workaround** (until the release pipeline is fixed to rewrite `plugin-dist/meta.json`
+against the exact `files`-filtered file set before publish, mirroring what
+`bundle-builtin-extensions.mjs` already does for the CLI-bundled distribution path):
+if you see `Could not resolve "@anthropic-ai/sdk"` on first load, run `npm install`
+in the environment to ensure the dependency is actually present, or call
+`rewriteArtifactSourceHash(installedDir)` (exported from `@x-otto/coding`) against
+the installed package directory before first load:
+
+```ts
+import { rewriteArtifactSourceHash } from '@x-otto/coding'
+rewriteArtifactSourceHash('/path/to/node_modules/@x-otto/plugin-otto-wire-protocols')
+```
+
+This is tracked as a release-pipeline follow-up, not a per-consumer workaround you
+should need long-term.
+
+## Dependencies
+
+- `@x-otto/provider` (workspace)
+- `@x-otto/interchange` (workspace)
+- `@x-otto/shared` (workspace)
+- `@anthropic-ai/sdk` (0.88.0)
+- `@x-otto/plugin` (dev, build-time only)

package/otto-plugin.json

@@ -0,0 +1,8 @@
+{
+  "id": "plugin-otto-wire-protocols",
+  "name": "Otto Wire Protocols",
+  "version": "1.0.0",
+  "description": "Three standard wire protocol implementations (anthropic-messages/openai-responses/openai-completions) — physically migrated out of the framework core (RFC-148). Provides runtime support for any declarative or code-based provider plugin that declares one of these wireApi values.",
+  "capabilities": ["wire-protocol"],
+  "engines": { "otto": ">=1.0.0" }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@x-otto/plugin-otto-wire-protocols",
+  "version": "0.1.0-alpha.14",
+  "private": false,
+  "description": "Three standard wire protocol implementations (anthropic-messages/openai-responses/openai-completions) — runtime support for provider plugins. Publishable standalone so non-CLI hosts (e.g. desktop apps depending only on @x-otto/coding) can install it without the full @x-otto/cli dependency tree.",
+  "dependencies": {
+    "@anthropic-ai/sdk": "0.88.0",
+    "@x-otto/shared": "0.1.0-alpha.14",
+    "@x-otto/interchange": "0.1.0-alpha.14",
+    "@x-otto/provider": "0.1.0-alpha.14",
+    "@x-otto/plugin": "0.1.0-alpha.14"
+  },
+  "type": "module",
+  "files": [
+    "otto-plugin.json",
+    "README.md",
+    "plugin.ts",
+    "src",
+    "plugin-dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "tag": "alpha"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/plugin-dist/meta.json

@@ -0,0 +1 @@
+{"apiVersion":1,"compilerVersion":"0.1.0-alpha.14","sourceHash":"e93b544b123bd6f45757457f819cbda2d08a419f276e399561dadf654f9abeb1"}