@proxitor/plugin-api 0.1.0-beta.0

package/README.md

@@ -0,0 +1,41 @@
+# @proxitor/plugin-api
+
+Published plugin contract for proxitor v1. Plugins transform a `CanonicalRequest`
+(IR) and observe/transform a `CanonicalEvent` stream; they are blind to
+providers, wire formats and transport (spec D9).
+
+## Mutations channels (and only these)
+
+1. The typed IR: `CanonicalRequest` (mutate and return from `onRequest`).
+2. `req.outboundHeaders` — upstream request headers. Protected (ignored on
+   conflict): `authorization`, `x-api-key`, `host`, `content-length`, and all
+   `provider.headers`.
+3. Format-reserved `$proxitor.` keys inside `req.extensions[format]`. Declare
+   them in `reservedKeys`; config-time validation matches the provider's
+   wireFormat. Reserved keys per format:
+
+   | format              | reserved keys                                                                   |
+   | ------------------- | ------------------------------------------------------------------------------- |
+   | `openai-chat`       | `$proxitor.provider`, `$proxitor.models`, `$proxitor.route`, `$proxitor.transforms` |
+   | `anthropic-messages` | — (none in v1)                                                                  |
+
+## ShortCircuit
+
+`{ shortCircuit: true, status, headers? }` plus **at most one** of `error`
+(CanonicalError, encoded to the client's wire-error format) or `events`
+(CanonicalEvent[], encoded to the client's inbound format — works for both
+streaming and non-streaming clients). Raw-body mocks are not supported.
+
+## definePlugin
+
+```ts
+import { definePlugin } from '@proxitor/plugin-api';
+import { z } from 'zod';
+
+export default definePlugin(z.object({ ttl: z.enum(['5m', '1h']) }), {
+  name: 'cache-control',
+  onRequest(ctx, req) { /* mutate req, return it */ return req; },
+});
+```
+
+zod is a peer dependency (`^4`).

package/dist/index.d.ts

@@ -0,0 +1,277 @@
+import { ZodType } from "zod";
+
+//#region src/canonical/request.d.ts
+/** Per-node passthrough for fields the IR does not model (spec §4.1, D17). */
+type NodeExtensions = Record<string, unknown>;
+/** Request-level passthrough bag keyed by source format (spec §4.3). */
+type ExtensionsBag = Record<string, Record<string, unknown>>;
+type CacheControl = {
+  type: 'ephemeral';
+  ttl?: '5m' | '1h';
+};
+type CanonicalSystemBlock = {
+  type: 'text';
+  text: string;
+  cacheControl?: CacheControl;
+  extensions?: NodeExtensions;
+};
+type ImageSource = {
+  kind: 'base64';
+  mediaType: string;
+  data: string;
+} | {
+  kind: 'url';
+  url: string;
+};
+type ResponseFormat = {
+  kind: 'json';
+} | {
+  kind: 'json_schema';
+  schema: Record<string, unknown>;
+};
+type CanonicalContentBlock = {
+  type: 'text';
+  text: string;
+  cacheControl?: CacheControl;
+  extensions?: NodeExtensions;
+} | {
+  type: 'image';
+  source: ImageSource;
+  cacheControl?: CacheControl;
+  extensions?: NodeExtensions;
+} | {
+  type: 'tool_use';
+  id: string;
+  name: string;
+  input: unknown;
+  cacheControl?: CacheControl;
+  extensions?: NodeExtensions;
+} | {
+  type: 'tool_result';
+  toolUseId: string;
+  content: CanonicalContentBlock[] | string;
+  isError?: boolean;
+  cacheControl?: CacheControl;
+  extensions?: NodeExtensions;
+} | {
+  type: 'thinking';
+  thinking: string;
+  signature?: string;
+  cacheControl?: CacheControl;
+  extensions?: NodeExtensions;
+};
+type CanonicalMessage = {
+  role: 'user' | 'assistant';
+  content: CanonicalContentBlock[];
+  extensions?: NodeExtensions;
+};
+type CanonicalTool = {
+  name: string;
+  description?: string;
+  inputSchema: Record<string, unknown>;
+  cacheControl?: CacheControl;
+};
+type CanonicalToolChoice = {
+  mode: 'auto' | 'any' | 'none';
+} | {
+  mode: 'tool';
+  name: string;
+};
+/** Provenance-preserving max tokens (r2 P0-1): same-format encode re-emits the source field name. */
+type MaxTokens = {
+  value: number;
+  source: 'max_tokens' | 'max_completion_tokens' | 'max_output_tokens';
+};
+type CanonicalParams = {
+  temperature?: number;
+  maxTokens?: MaxTokens;
+  topP?: number;
+  topK?: number;
+  stop?: string[];
+  seed?: number;
+  n?: number;
+  responseFormat?: ResponseFormat;
+  presencePenalty?: number;
+  frequencyPenalty?: number;
+};
+type CanonicalRequest = {
+  model: {
+    logical: string;
+    physical: string;
+  };
+  system: CanonicalSystemBlock[];
+  messages: CanonicalMessage[];
+  tools?: CanonicalTool[];
+  toolChoice?: CanonicalToolChoice;
+  params: CanonicalParams;
+  stream: boolean;
+  extensions: ExtensionsBag; /** Plugin → upstream header channel (D18); auth + provider.headers are protected. */
+  outboundHeaders?: Record<string, string>; /** Inbound client session hint, stamped by the pipeline from client headers; plugins may honor it instead of deriving their own id. */
+  clientSessionId?: string;
+};
+//#endregion
+//#region src/canonical/events.d.ts
+type StopReason = 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use';
+type Usage = {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens?: number;
+  cacheCreateTokens?: number;
+};
+type PartialUsage = Partial<Usage>;
+type TextDelta = {
+  type: 'text';
+  text: string;
+};
+type InputJsonDelta = {
+  type: 'input_json';
+  partialJson: string;
+};
+type ThinkingDelta = {
+  type: 'thinking';
+  thinking: string;
+};
+type CanonicalError = {
+  type: string;
+  message: string;
+  status: number;
+  providerError?: unknown;
+};
+type CanonicalEvent = {
+  type: 'message_start';
+  id: string;
+  model: string;
+} | {
+  type: 'content_block_start';
+  index: number;
+  block: {
+    type: 'text' | 'tool_use' | 'thinking';
+    id?: string;
+    name?: string;
+  };
+} | {
+  type: 'content_block_delta';
+  index: number;
+  delta: TextDelta | InputJsonDelta | ThinkingDelta;
+} | {
+  type: 'signature_delta';
+  index: number;
+  signature: string;
+} | {
+  type: 'content_block_stop';
+  index: number;
+} | {
+  type: 'message_delta';
+  stopReason?: StopReason;
+  stopSequence?: string | null;
+  usage?: PartialUsage; /** Raw wire provenance the IR cannot express, e.g. openai `finish_reason` (spec §4.2). */
+  extensions?: NodeExtensions;
+} | {
+  type: 'message_stop';
+} | {
+  type: 'ping';
+} | {
+  type: 'usage';
+  usage: Usage;
+} | {
+  type: 'error';
+  error: CanonicalError;
+};
+//#endregion
+//#region src/ports.d.ts
+type LoggerPort = {
+  info(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  error(message: string, context?: Record<string, unknown>): void;
+  debug(message: string, context?: Record<string, unknown>): void;
+};
+type ClockPort = {
+  now(): number;
+};
+type RandomPort = {
+  uuid(): string;
+};
+//#endregion
+//#region src/wire-format.d.ts
+declare const WIRE_FORMATS: readonly ["anthropic-messages", "openai-chat"];
+type WireFormat = (typeof WIRE_FORMATS)[number];
+/**
+ * Format-reserved extension keys (spec §4.3): the only keys a plugin may write
+ * into `ir.extensions[format]`. Public contract — keep in sync with README.
+ */
+declare const RESERVED_KEYS: Readonly<Record<WireFormat, readonly string[]>>;
+/**
+ * Endpoint path each wire format owns (spec §5.1): the format adapter owns the
+ * version path; a provider `baseUrl` is everything before it. Consumed by
+ * domain routing for baseUrl validation and upstream URL construction.
+ */
+declare const ENDPOINT_PATHS: Readonly<Record<WireFormat, string>>;
+/**
+ * Inbound proxy-owned paths (spec §5.2): `/v1/models` is synthesized locally
+ * from the routing table; `/v1/responses` (openai-responses format) is
+ * deferred — classified to a 501 (§17), never a passthrough.
+ */
+declare const MODELS_PATH = "/v1/models";
+declare const DEFERRED_RESPONSES_PATH = "/v1/responses";
+/**
+ * Session headers (spec §10a): the pipeline stamps the first present value onto
+ * `CanonicalRequest.clientSessionId`; the session-id plugin forwards it upstream.
+ */
+declare const CLIENT_SESSION_ID_HEADER = "x-claude-code-session-id";
+declare const SESSION_ID_HEADER = "x-session-id";
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * Plugin-initiated response without hitting upstream (spec §7).
+ * `error` XOR `events`: error is encoded to the client's wire-error format,
+ * events are encoded to the client's inbound format (format-agnostic mock).
+ * Raw-body mocks are intentionally NOT supported (D9).
+ */
+type ShortCircuit = {
+  shortCircuit: true;
+  status: number;
+  headers?: Record<string, string>;
+  error?: CanonicalError;
+  events?: CanonicalEvent[];
+} & ({
+  error: CanonicalError;
+  events?: never;
+} | {
+  events?: CanonicalEvent[];
+  error?: never;
+});
+type PluginContext<TConfig = unknown> = {
+  requestId: string;
+  logger: LoggerPort;
+  clock: ClockPort;
+  random: RandomPort;
+  config: TConfig;
+};
+type ProxyPlugin<TConfig = unknown> = {
+  /** Unique instance id: dedup across config layers. */name: string;
+  validateConfig?(raw: unknown): TConfig;
+  /**
+   * Declares which format-reserved `$proxitor.` keys this plugin writes (spec §4.3).
+   * Config-time validation matches these against the provider's wireFormat.
+   */
+  reservedKeys?: Partial<Record<WireFormat, readonly string[]>>;
+  onRequest?(ctx: PluginContext<TConfig>, req: CanonicalRequest): Promise<CanonicalRequest | ShortCircuit> | CanonicalRequest | ShortCircuit;
+  onEvent?(ctx: PluginContext<TConfig>, event: CanonicalEvent): Promise<void> | void;
+  transformStream?(ctx: PluginContext<TConfig>, events: AsyncIterable<CanonicalEvent>): AsyncIterable<CanonicalEvent>;
+  onError?(ctx: PluginContext<TConfig>, error: CanonicalError): Promise<CanonicalError> | CanonicalError;
+};
+//#endregion
+//#region src/define-plugin.d.ts
+type PluginWithoutValidate<TConfig> = Omit<ProxyPlugin<TConfig>, 'validateConfig'>;
+/**
+ * The only runtime helper in the package: attaches a zod-backed validateConfig
+ * to a plugin (spec §7). Overload without a schema passes the plugin through.
+ */
+declare function definePlugin<TConfig>(plugin: ProxyPlugin<TConfig>): ProxyPlugin<TConfig>;
+declare function definePlugin<TConfig>(schema: ZodType<TConfig>, plugin: PluginWithoutValidate<TConfig>): ProxyPlugin<TConfig>;
+//#endregion
+//#region src/index.d.ts
+declare const PLUGIN_API_VERSION = "0.0.0";
+//#endregion
+export { CLIENT_SESSION_ID_HEADER, CacheControl, CanonicalContentBlock, CanonicalError, CanonicalEvent, CanonicalMessage, CanonicalParams, CanonicalRequest, CanonicalSystemBlock, CanonicalTool, CanonicalToolChoice, ClockPort, DEFERRED_RESPONSES_PATH, ENDPOINT_PATHS, ExtensionsBag, ImageSource, InputJsonDelta, LoggerPort, MODELS_PATH, MaxTokens, NodeExtensions, PLUGIN_API_VERSION, PartialUsage, PluginContext, ProxyPlugin, RESERVED_KEYS, RandomPort, ResponseFormat, SESSION_ID_HEADER, ShortCircuit, StopReason, TextDelta, ThinkingDelta, Usage, WIRE_FORMATS, WireFormat, definePlugin };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/canonical/request.ts","../src/canonical/events.ts","../src/ports.ts","../src/wire-format.ts","../src/plugin.ts","../src/define-plugin.ts","../src/index.ts"],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,54 @@
+//#region src/define-plugin.ts
+function definePlugin(schemaOrPlugin, maybePlugin) {
+	if (maybePlugin === void 0) return schemaOrPlugin;
+	const schema = schemaOrPlugin;
+	return {
+		...maybePlugin,
+		validateConfig: (raw) => schema.parse(raw)
+	};
+}
+//#endregion
+//#region src/wire-format.ts
+const WIRE_FORMATS = ["anthropic-messages", "openai-chat"];
+/**
+* Format-reserved extension keys (spec §4.3): the only keys a plugin may write
+* into `ir.extensions[format]`. Public contract — keep in sync with README.
+*/
+const RESERVED_KEYS = {
+	"anthropic-messages": [],
+	"openai-chat": [
+		"$proxitor.provider",
+		"$proxitor.models",
+		"$proxitor.route",
+		"$proxitor.transforms"
+	]
+};
+/**
+* Endpoint path each wire format owns (spec §5.1): the format adapter owns the
+* version path; a provider `baseUrl` is everything before it. Consumed by
+* domain routing for baseUrl validation and upstream URL construction.
+*/
+const ENDPOINT_PATHS = {
+	"anthropic-messages": "/v1/messages",
+	"openai-chat": "/v1/chat/completions"
+};
+/**
+* Inbound proxy-owned paths (spec §5.2): `/v1/models` is synthesized locally
+* from the routing table; `/v1/responses` (openai-responses format) is
+* deferred — classified to a 501 (§17), never a passthrough.
+*/
+const MODELS_PATH = "/v1/models";
+const DEFERRED_RESPONSES_PATH = "/v1/responses";
+/**
+* Session headers (spec §10a): the pipeline stamps the first present value onto
+* `CanonicalRequest.clientSessionId`; the session-id plugin forwards it upstream.
+*/
+const CLIENT_SESSION_ID_HEADER = "x-claude-code-session-id";
+const SESSION_ID_HEADER = "x-session-id";
+//#endregion
+//#region src/index.ts
+const PLUGIN_API_VERSION = "0.0.0";
+//#endregion
+export { CLIENT_SESSION_ID_HEADER, DEFERRED_RESPONSES_PATH, ENDPOINT_PATHS, MODELS_PATH, PLUGIN_API_VERSION, RESERVED_KEYS, SESSION_ID_HEADER, WIRE_FORMATS, definePlugin };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/define-plugin.ts","../src/wire-format.ts","../src/index.ts"],"sourcesContent":["import type { ZodType } from 'zod';\nimport type { ProxyPlugin } from './plugin.js';\n\ntype PluginWithoutValidate<TConfig> = Omit<ProxyPlugin<TConfig>, 'validateConfig'>;\n\n/**\n * The only runtime helper in the package: attaches a zod-backed validateConfig\n * to a plugin (spec §7). Overload without a schema passes the plugin through.\n */\nexport function definePlugin<TConfig>(plugin: ProxyPlugin<TConfig>): ProxyPlugin<TConfig>;\nexport function definePlugin<TConfig>(\n  schema: ZodType<TConfig>,\n  plugin: PluginWithoutValidate<TConfig>,\n): ProxyPlugin<TConfig>;\nexport function definePlugin<TConfig>(\n  schemaOrPlugin: ZodType<TConfig> | ProxyPlugin<TConfig>,\n  maybePlugin?: PluginWithoutValidate<TConfig>,\n): ProxyPlugin<TConfig> {\n  if (maybePlugin === undefined) {\n    return schemaOrPlugin as ProxyPlugin<TConfig>;\n  }\n  const schema = schemaOrPlugin as ZodType<TConfig>;\n  return {\n    ...maybePlugin,\n    validateConfig: (raw: unknown): TConfig => schema.parse(raw),\n  };\n}\n","export const WIRE_FORMATS = ['anthropic-messages', 'openai-chat'] as const;\n\nexport type WireFormat = (typeof WIRE_FORMATS)[number];\n\n/**\n * Format-reserved extension keys (spec §4.3): the only keys a plugin may write\n * into `ir.extensions[format]`. Public contract — keep in sync with README.\n */\nexport const RESERVED_KEYS: Readonly<Record<WireFormat, readonly string[]>> = {\n  'anthropic-messages': [],\n  'openai-chat': [\n    '$proxitor.provider',\n    '$proxitor.models',\n    '$proxitor.route',\n    '$proxitor.transforms',\n  ],\n};\n\n/**\n * Endpoint path each wire format owns (spec §5.1): the format adapter owns the\n * version path; a provider `baseUrl` is everything before it. Consumed by\n * domain routing for baseUrl validation and upstream URL construction.\n */\nexport const ENDPOINT_PATHS: Readonly<Record<WireFormat, string>> = {\n  'anthropic-messages': '/v1/messages',\n  'openai-chat': '/v1/chat/completions',\n};\n\n/**\n * Inbound proxy-owned paths (spec §5.2): `/v1/models` is synthesized locally\n * from the routing table; `/v1/responses` (openai-responses format) is\n * deferred — classified to a 501 (§17), never a passthrough.\n */\nexport const MODELS_PATH = '/v1/models';\nexport const DEFERRED_RESPONSES_PATH = '/v1/responses';\n\n/**\n * Session headers (spec §10a): the pipeline stamps the first present value onto\n * `CanonicalRequest.clientSessionId`; the session-id plugin forwards it upstream.\n */\nexport const CLIENT_SESSION_ID_HEADER = 'x-claude-code-session-id';\nexport const SESSION_ID_HEADER = 'x-session-id';\n","export const PLUGIN_API_VERSION = '0.0.0';\n\nexport * from './canonical/events.js';\nexport * from './canonical/request.js';\nexport * from './define-plugin.js';\nexport * from './plugin.js';\nexport * from './ports.js';\nexport * from './wire-format.js';\n"],"mappings":";AAcA,SAAgB,aACd,gBACA,aACsB;CACtB,IAAI,gBAAgB,KAAA,GAClB,OAAO;CAET,MAAM,SAAS;CACf,OAAO;EACL,GAAG;EACH,iBAAiB,QAA0B,OAAO,MAAM,GAAG;CAC7D;AACF;;;AC1BA,MAAa,eAAe,CAAC,sBAAsB,aAAa;;;;;AAQhE,MAAa,gBAAiE;CAC5E,sBAAsB,CAAC;CACvB,eAAe;EACb;EACA;EACA;EACA;CACF;AACF;;;;;;AAOA,MAAa,iBAAuD;CAClE,sBAAsB;CACtB,eAAe;AACjB;;;;;;AAOA,MAAa,cAAc;AAC3B,MAAa,0BAA0B;;;;;AAMvC,MAAa,2BAA2B;AACxC,MAAa,oBAAoB;;;ACzCjC,MAAa,qBAAqB"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@proxitor/plugin-api",
+  "version": "0.1.0-beta.0",
+  "description": "Published proxitor plugin contract: Canonical IR, plugin hooks, ports",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:types": "vitest run --typecheck",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.1",
+    "vitest": "^4.1.8",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    }
+  }
+}