@graphorin/server 0.5.0

package/dist/middleware/scope.d.ts

@@ -0,0 +1,24 @@
+import { ServerVariables } from "../internal/context.js";
+import { MiddlewareHandler } from "hono";
+import { ParsedScope } from "@graphorin/security/auth";
+
+//#region src/middleware/scope.d.ts
+
+/**
+ * Required-scope spec accepted by {@link createScopeMiddleware}. Either
+ * a single string (`'agents:invoke'`), a parsed scope, or a function
+ * that derives the required scope from the request (e.g. to insert the
+ * `:id` segment lazily).
+ *
+ * @stable
+ */
+type ScopeRequirement = string | ParsedScope | ((path: string, params: Record<string, string>) => string | ParsedScope);
+/**
+ * @stable
+ */
+declare function createScopeMiddleware(requirement: ScopeRequirement): MiddlewareHandler<{
+  Variables: ServerVariables;
+}>;
+//#endregion
+export { ScopeRequirement, createScopeMiddleware };
+//# sourceMappingURL=scope.d.ts.map

package/dist/middleware/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","names":[],"sources":["../../src/middleware/scope.ts"],"sourcesContent":[],"mappings":";;;;;;AA6BA;;;;;;;;KARY,gBAAA,YAER,sCACwB,oCAAoC;;;;iBAKhD,qBAAA,cACD,mBACZ;aAA+B"}

package/dist/middleware/scope.js

@@ -0,0 +1,50 @@
+import { parseScope, scopeMatches } from "@graphorin/security/auth";
+
+//#region src/middleware/scope.ts
+/**
+* Per-route scope enforcement. Reads the verified token populated by
+* the auth middleware and short-circuits with `403` when the granted
+* set does not match the required scope.
+*
+* @packageDocumentation
+*/
+/**
+* @stable
+*/
+function createScopeMiddleware(requirement) {
+	return async (c, next) => {
+		const auth = c.get("state").auth;
+		if (auth.kind === "anonymous") {
+			await next();
+			return;
+		}
+		if (auth.kind === "unauthenticated") return c.json({
+			error: "auth-required",
+			message: "Authentication required for this endpoint."
+		}, 401);
+		const required = resolveRequirement(requirement, c.req.path, c.req.param());
+		const granted = auth.grantedScopes;
+		let allowed = false;
+		for (const scope of granted) if (scopeMatches(scope, required)) {
+			allowed = true;
+			break;
+		}
+		if (!allowed) return c.json({
+			error: "scope-denied",
+			message: `Token lacks required scope '${required.raw}'.`,
+			hint: `Mint a token with the '${required.raw}' (or admin:*) scope.`
+		}, 403);
+		await next();
+	};
+}
+function resolveRequirement(requirement, path, params) {
+	if (typeof requirement === "function") {
+		const next = requirement(path, params);
+		return typeof next === "string" ? parseScope(next) : next;
+	}
+	return typeof requirement === "string" ? parseScope(requirement) : requirement;
+}
+
+//#endregion
+export { createScopeMiddleware };
+//# sourceMappingURL=scope.js.map

package/dist/middleware/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","names":[],"sources":["../../src/middleware/scope.ts"],"sourcesContent":["/**\n * Per-route scope enforcement. Reads the verified token populated by\n * the auth middleware and short-circuits with `403` when the granted\n * set does not match the required scope.\n *\n * @packageDocumentation\n */\n\nimport { type ParsedScope, parseScope, scopeMatches } from '@graphorin/security/auth';\nimport type { MiddlewareHandler } from 'hono';\n\nimport type { ServerVariables } from '../internal/context.js';\n\n/**\n * Required-scope spec accepted by {@link createScopeMiddleware}. Either\n * a single string (`'agents:invoke'`), a parsed scope, or a function\n * that derives the required scope from the request (e.g. to insert the\n * `:id` segment lazily).\n *\n * @stable\n */\nexport type ScopeRequirement =\n  | string\n  | ParsedScope\n  | ((path: string, params: Record<string, string>) => string | ParsedScope);\n\n/**\n * @stable\n */\nexport function createScopeMiddleware(\n  requirement: ScopeRequirement,\n): MiddlewareHandler<{ Variables: ServerVariables }> {\n  return async (c, next) => {\n    const auth = c.get('state').auth;\n    if (auth.kind === 'anonymous') {\n      // IP-13: auth is disabled server-wide (auth.kind='none'). There is no\n      // token to scope-check — the trusted-loopback operator is allowed\n      // through every gate.\n      await next();\n      return;\n    }\n    if (auth.kind === 'unauthenticated') {\n      return c.json(\n        {\n          error: 'auth-required',\n          message: 'Authentication required for this endpoint.',\n        },\n        401,\n      );\n    }\n    const required = resolveRequirement(\n      requirement,\n      c.req.path,\n      c.req.param() as Record<string, string>,\n    );\n    const granted = auth.grantedScopes;\n    let allowed = false;\n    for (const scope of granted) {\n      if (scopeMatches(scope, required)) {\n        allowed = true;\n        break;\n      }\n    }\n    if (!allowed) {\n      return c.json(\n        {\n          error: 'scope-denied',\n          message: `Token lacks required scope '${required.raw}'.`,\n          hint: `Mint a token with the '${required.raw}' (or admin:*) scope.`,\n        },\n        403,\n      );\n    }\n    await next();\n  };\n}\n\nfunction resolveRequirement(\n  requirement: ScopeRequirement,\n  path: string,\n  params: Record<string, string>,\n): ParsedScope {\n  if (typeof requirement === 'function') {\n    const next = requirement(path, params);\n    return typeof next === 'string' ? parseScope(next) : next;\n  }\n  return typeof requirement === 'string' ? parseScope(requirement) : requirement;\n}\n"],"mappings":";;;;;;;;;;;;;AA6BA,SAAgB,sBACd,aACmD;AACnD,QAAO,OAAO,GAAG,SAAS;EACxB,MAAM,OAAO,EAAE,IAAI,QAAQ,CAAC;AAC5B,MAAI,KAAK,SAAS,aAAa;AAI7B,SAAM,MAAM;AACZ;;AAEF,MAAI,KAAK,SAAS,kBAChB,QAAO,EAAE,KACP;GACE,OAAO;GACP,SAAS;GACV,EACD,IACD;EAEH,MAAM,WAAW,mBACf,aACA,EAAE,IAAI,MACN,EAAE,IAAI,OAAO,CACd;EACD,MAAM,UAAU,KAAK;EACrB,IAAI,UAAU;AACd,OAAK,MAAM,SAAS,QAClB,KAAI,aAAa,OAAO,SAAS,EAAE;AACjC,aAAU;AACV;;AAGJ,MAAI,CAAC,QACH,QAAO,EAAE,KACP;GACE,OAAO;GACP,SAAS,+BAA+B,SAAS,IAAI;GACrD,MAAM,0BAA0B,SAAS,IAAI;GAC9C,EACD,IACD;AAEH,QAAM,MAAM;;;AAIhB,SAAS,mBACP,aACA,MACA,QACa;AACb,KAAI,OAAO,gBAAgB,YAAY;EACrC,MAAM,OAAO,YAAY,MAAM,OAAO;AACtC,SAAO,OAAO,SAAS,WAAW,WAAW,KAAK,GAAG;;AAEvD,QAAO,OAAO,gBAAgB,WAAW,WAAW,YAAY,GAAG"}

package/dist/registry/index.d.ts

@@ -0,0 +1,135 @@
+//#region src/registry/index.d.ts
+/**
+ * Registry plumbing that lets the server route handlers locate user-
+ * defined agents, workflows, sessions, memory, skills, and MCP
+ * server bindings without taking a hard peer dependency on every
+ * sibling package.
+ *
+ * Every entry is keyed by string id; lookups never throw — callers
+ * receive `undefined` and the route handler decides how to surface
+ * the miss (typically a 404 with a typed error body).
+ *
+ * @packageDocumentation
+ */
+/**
+ * Minimal shape the server needs from an `Agent`. Compatible with
+ * the `Agent` interface from `@graphorin/agent` but kept
+ * structurally so we avoid the peer dependency.
+ *
+ * @stable
+ */
+interface ServerAgentLike {
+  readonly id: string;
+  run(input: unknown, options?: {
+    readonly signal?: AbortSignal;
+    readonly sessionId?: string;
+    readonly userId?: string;
+  }): Promise<unknown>;
+  /**
+   * Streaming surface (IP-2). `@graphorin/agent` agents satisfy this
+   * structurally; `POST /agents/:id/stream` consumes it and emits
+   * every event onto the run's WS subject. Optional so plain
+   * run-only fixtures keep working (they emit a single terminal frame).
+   */
+  stream?(input: unknown, options?: {
+    readonly signal?: AbortSignal;
+    readonly sessionId?: string;
+    readonly userId?: string;
+  }): AsyncIterable<unknown>;
+}
+/**
+ * Minimal shape the server needs from a `Workflow`. Mirrors the
+ * `Workflow` surface from `@graphorin/workflow`.
+ *
+ * @stable
+ */
+interface ServerWorkflowLike {
+  readonly name: string;
+  execute(input: unknown, options?: {
+    readonly signal?: AbortSignal;
+    readonly threadId?: string;
+  }): AsyncIterable<unknown>;
+  resume?(threadId: string, directive?: {
+    readonly resume?: unknown;
+  }): AsyncIterable<unknown>;
+  getState?(threadId: string): Promise<unknown>;
+  listCheckpoints?(threadId: string): Promise<ReadonlyArray<unknown>>;
+}
+/**
+ * Snapshot record returned by {@link AgentRegistry.list}.
+ *
+ * @stable
+ */
+interface AgentSummary {
+  readonly id: string;
+  readonly description?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+/**
+ * Snapshot record returned by {@link WorkflowRegistry.list}.
+ *
+ * @stable
+ */
+interface WorkflowSummary {
+  readonly id: string;
+  readonly description?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+/**
+ * Registration descriptor accepted by {@link AgentRegistry.register}.
+ *
+ * @stable
+ */
+interface AgentRegistration {
+  readonly id: string;
+  readonly agent: ServerAgentLike;
+  readonly description?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+/**
+ * Registration descriptor accepted by {@link WorkflowRegistry.register}.
+ *
+ * @stable
+ */
+interface WorkflowRegistration {
+  readonly id: string;
+  readonly workflow: ServerWorkflowLike;
+  readonly description?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+/**
+ * Read/write registry for agents the server should expose. Every
+ * mutation is synchronous and the lookup is `O(1)`.
+ *
+ * The class is intentionally tiny — extension points (e.g. lazy
+ * factory loading, per-tenant scoping) live in higher-level packages
+ * and consume this surface as a primitive.
+ *
+ * @stable
+ */
+declare class AgentRegistry {
+  #private;
+  register(entry: AgentRegistration): void;
+  unregister(id: string): boolean;
+  get(id: string): ServerAgentLike | undefined;
+  has(id: string): boolean;
+  list(): ReadonlyArray<AgentSummary>;
+  describe(id: string): AgentSummary | undefined;
+  size(): number;
+}
+/**
+ * @stable
+ */
+declare class WorkflowRegistry {
+  #private;
+  register(entry: WorkflowRegistration): void;
+  unregister(id: string): boolean;
+  get(id: string): ServerWorkflowLike | undefined;
+  has(id: string): boolean;
+  list(): ReadonlyArray<WorkflowSummary>;
+  describe(id: string): WorkflowSummary | undefined;
+  size(): number;
+}
+//#endregion
+export { AgentRegistration, AgentRegistry, AgentSummary, ServerAgentLike, ServerWorkflowLike, WorkflowRegistration, WorkflowRegistry, WorkflowSummary };
+//# sourceMappingURL=index.d.ts.map

package/dist/registry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/registry/index.ts"],"sourcesContent":[],"mappings":";;AAoBA;;;;;;AAgCA;;;;;;;;AAgBA;AAWA;AAkCA;AAYA;AAiBa,UA1HI,eAAA,CA0HS;EAGR,SAAA,EAAA,EAAA,MAAA;EAaC,GAAA,CAAA,KAAA,EAAA,OAAA,EAAA,OAoBiB,CApBjB,EAAA;IAQK,SAAA,MAAA,CAAA,EA7IA,WA6IA;IAAd,SAAA,SAAA,CAAA,EAAA,MAAA;IAYc,SAAA,MAAA,CAAA,EAAA,MAAA;EAAY,CAAA,CAAA,EArJ/B,OAqJ+B,CAAA,OAAA,CAAA;EAkBvB;;;;;;EAoC0B,MAAA,EAAA,KAAA,EAAA,OAAA,EAAA,QAAA,EAAA;sBAjMf;;;MAInB;;;;;;;;UASY,kBAAA;;;sBAIiB;;MAC7B;;;MACmE;+BACzC;sCACO,QAAQ;;;;;;;UAQ7B,YAAA;;;kBAGC;;;;;;;UAQD,eAAA;;;kBAGC;;;;;;;UA+BD,iBAAA;;kBAEC;;kBAEA;;;;;;;UAQD,oBAAA;;qBAEI;;kBAEH;;;;;;;;;;;;cAaL,aAAA;;kBAGK;;mBAaC;;UAQT,cAAc;wBAYA;;;;;;cAkBX,gBAAA;;kBAGK;;mBAaC;;UAQT,cAAc;wBAYA"}

package/dist/registry/index.js

@@ -0,0 +1,96 @@
+//#region src/registry/index.ts
+/**
+* Read/write registry for agents the server should expose. Every
+* mutation is synchronous and the lookup is `O(1)`.
+*
+* The class is intentionally tiny — extension points (e.g. lazy
+* factory loading, per-tenant scoping) live in higher-level packages
+* and consume this surface as a primitive.
+*
+* @stable
+*/
+var AgentRegistry = class {
+	#entries = /* @__PURE__ */ new Map();
+	register(entry) {
+		this.#entries.set(entry.id, {
+			id: entry.id,
+			agent: entry.agent,
+			...entry.description !== void 0 ? { description: entry.description } : {},
+			...entry.tags !== void 0 ? { tags: Object.freeze(entry.tags.slice()) } : {}
+		});
+	}
+	unregister(id) {
+		return this.#entries.delete(id);
+	}
+	get(id) {
+		return this.#entries.get(id)?.agent;
+	}
+	has(id) {
+		return this.#entries.has(id);
+	}
+	list() {
+		return Object.freeze([...this.#entries.values()].map((entry) => Object.freeze({
+			id: entry.id,
+			...entry.description !== void 0 ? { description: entry.description } : {},
+			...entry.tags !== void 0 ? { tags: entry.tags } : {}
+		})));
+	}
+	describe(id) {
+		const entry = this.#entries.get(id);
+		if (entry === void 0) return void 0;
+		return Object.freeze({
+			id: entry.id,
+			...entry.description !== void 0 ? { description: entry.description } : {},
+			...entry.tags !== void 0 ? { tags: entry.tags } : {}
+		});
+	}
+	size() {
+		return this.#entries.size;
+	}
+};
+/**
+* @stable
+*/
+var WorkflowRegistry = class {
+	#entries = /* @__PURE__ */ new Map();
+	register(entry) {
+		this.#entries.set(entry.id, {
+			id: entry.id,
+			workflow: entry.workflow,
+			...entry.description !== void 0 ? { description: entry.description } : {},
+			...entry.tags !== void 0 ? { tags: Object.freeze(entry.tags.slice()) } : {}
+		});
+	}
+	unregister(id) {
+		return this.#entries.delete(id);
+	}
+	get(id) {
+		return this.#entries.get(id)?.workflow;
+	}
+	has(id) {
+		return this.#entries.has(id);
+	}
+	list() {
+		return Object.freeze([...this.#entries.values()].map((entry) => Object.freeze({
+			id: entry.id,
+			...entry.description !== void 0 ? { description: entry.description } : {},
+			...entry.tags !== void 0 ? { tags: entry.tags } : {}
+		})));
+	}
+	describe(id) {
+		const entry = this.#entries.get(id);
+		if (entry === void 0) return void 0;
+		return Object.freeze({
+			id: entry.id,
+			...entry.description !== void 0 ? { description: entry.description } : {},
+			...entry.tags !== void 0 ? { tags: entry.tags } : {}
+		});
+	}
+	size() {
+		return this.#entries.size;
+	}
+};
+
+//#endregion
+export { AgentRegistry, WorkflowRegistry };
+//# sourceMappingURL=index.js.map

package/dist/registry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["#entries"],"sources":["../../src/registry/index.ts"],"sourcesContent":["/**\n * Registry plumbing that lets the server route handlers locate user-\n * defined agents, workflows, sessions, memory, skills, and MCP\n * server bindings without taking a hard peer dependency on every\n * sibling package.\n *\n * Every entry is keyed by string id; lookups never throw — callers\n * receive `undefined` and the route handler decides how to surface\n * the miss (typically a 404 with a typed error body).\n *\n * @packageDocumentation\n */\n\n/**\n * Minimal shape the server needs from an `Agent`. Compatible with\n * the `Agent` interface from `@graphorin/agent` but kept\n * structurally so we avoid the peer dependency.\n *\n * @stable\n */\nexport interface ServerAgentLike {\n  readonly id: string;\n  run(\n    input: unknown,\n    options?: {\n      readonly signal?: AbortSignal;\n      readonly sessionId?: string;\n      readonly userId?: string;\n    },\n  ): Promise<unknown>;\n  /**\n   * Streaming surface (IP-2). `@graphorin/agent` agents satisfy this\n   * structurally; `POST /agents/:id/stream` consumes it and emits\n   * every event onto the run's WS subject. Optional so plain\n   * run-only fixtures keep working (they emit a single terminal frame).\n   */\n  stream?(\n    input: unknown,\n    options?: {\n      readonly signal?: AbortSignal;\n      readonly sessionId?: string;\n      readonly userId?: string;\n    },\n  ): AsyncIterable<unknown>;\n}\n\n/**\n * Minimal shape the server needs from a `Workflow`. Mirrors the\n * `Workflow` surface from `@graphorin/workflow`.\n *\n * @stable\n */\nexport interface ServerWorkflowLike {\n  readonly name: string;\n  execute(\n    input: unknown,\n    options?: { readonly signal?: AbortSignal; readonly threadId?: string },\n  ): AsyncIterable<unknown>;\n  resume?(threadId: string, directive?: { readonly resume?: unknown }): AsyncIterable<unknown>;\n  getState?(threadId: string): Promise<unknown>;\n  listCheckpoints?(threadId: string): Promise<ReadonlyArray<unknown>>;\n}\n\n/**\n * Snapshot record returned by {@link AgentRegistry.list}.\n *\n * @stable\n */\nexport interface AgentSummary {\n  readonly id: string;\n  readonly description?: string;\n  readonly tags?: ReadonlyArray<string>;\n}\n\n/**\n * Snapshot record returned by {@link WorkflowRegistry.list}.\n *\n * @stable\n */\nexport interface WorkflowSummary {\n  readonly id: string;\n  readonly description?: string;\n  readonly tags?: ReadonlyArray<string>;\n}\n\n/**\n * Internal registry entry — pairs the user-supplied object with the\n * metadata routes serve to clients.\n *\n * @internal\n */\ninterface AgentEntry {\n  readonly id: string;\n  readonly agent: ServerAgentLike;\n  readonly description?: string;\n  readonly tags?: ReadonlyArray<string>;\n}\n\n/**\n * @internal\n */\ninterface WorkflowEntry {\n  readonly id: string;\n  readonly workflow: ServerWorkflowLike;\n  readonly description?: string;\n  readonly tags?: ReadonlyArray<string>;\n}\n\n/**\n * Registration descriptor accepted by {@link AgentRegistry.register}.\n *\n * @stable\n */\nexport interface AgentRegistration {\n  readonly id: string;\n  readonly agent: ServerAgentLike;\n  readonly description?: string;\n  readonly tags?: ReadonlyArray<string>;\n}\n\n/**\n * Registration descriptor accepted by {@link WorkflowRegistry.register}.\n *\n * @stable\n */\nexport interface WorkflowRegistration {\n  readonly id: string;\n  readonly workflow: ServerWorkflowLike;\n  readonly description?: string;\n  readonly tags?: ReadonlyArray<string>;\n}\n\n/**\n * Read/write registry for agents the server should expose. Every\n * mutation is synchronous and the lookup is `O(1)`.\n *\n * The class is intentionally tiny — extension points (e.g. lazy\n * factory loading, per-tenant scoping) live in higher-level packages\n * and consume this surface as a primitive.\n *\n * @stable\n */\nexport class AgentRegistry {\n  readonly #entries: Map<string, AgentEntry> = new Map();\n\n  register(entry: AgentRegistration): void {\n    this.#entries.set(entry.id, {\n      id: entry.id,\n      agent: entry.agent,\n      ...(entry.description !== undefined ? { description: entry.description } : {}),\n      ...(entry.tags !== undefined ? { tags: Object.freeze(entry.tags.slice()) } : {}),\n    });\n  }\n\n  unregister(id: string): boolean {\n    return this.#entries.delete(id);\n  }\n\n  get(id: string): ServerAgentLike | undefined {\n    return this.#entries.get(id)?.agent;\n  }\n\n  has(id: string): boolean {\n    return this.#entries.has(id);\n  }\n\n  list(): ReadonlyArray<AgentSummary> {\n    return Object.freeze(\n      [...this.#entries.values()].map((entry) =>\n        Object.freeze({\n          id: entry.id,\n          ...(entry.description !== undefined ? { description: entry.description } : {}),\n          ...(entry.tags !== undefined ? { tags: entry.tags } : {}),\n        }),\n      ),\n    );\n  }\n\n  describe(id: string): AgentSummary | undefined {\n    const entry = this.#entries.get(id);\n    if (entry === undefined) return undefined;\n    return Object.freeze({\n      id: entry.id,\n      ...(entry.description !== undefined ? { description: entry.description } : {}),\n      ...(entry.tags !== undefined ? { tags: entry.tags } : {}),\n    });\n  }\n\n  size(): number {\n    return this.#entries.size;\n  }\n}\n\n/**\n * @stable\n */\nexport class WorkflowRegistry {\n  readonly #entries: Map<string, WorkflowEntry> = new Map();\n\n  register(entry: WorkflowRegistration): void {\n    this.#entries.set(entry.id, {\n      id: entry.id,\n      workflow: entry.workflow,\n      ...(entry.description !== undefined ? { description: entry.description } : {}),\n      ...(entry.tags !== undefined ? { tags: Object.freeze(entry.tags.slice()) } : {}),\n    });\n  }\n\n  unregister(id: string): boolean {\n    return this.#entries.delete(id);\n  }\n\n  get(id: string): ServerWorkflowLike | undefined {\n    return this.#entries.get(id)?.workflow;\n  }\n\n  has(id: string): boolean {\n    return this.#entries.has(id);\n  }\n\n  list(): ReadonlyArray<WorkflowSummary> {\n    return Object.freeze(\n      [...this.#entries.values()].map((entry) =>\n        Object.freeze({\n          id: entry.id,\n          ...(entry.description !== undefined ? { description: entry.description } : {}),\n          ...(entry.tags !== undefined ? { tags: entry.tags } : {}),\n        }),\n      ),\n    );\n  }\n\n  describe(id: string): WorkflowSummary | undefined {\n    const entry = this.#entries.get(id);\n    if (entry === undefined) return undefined;\n    return Object.freeze({\n      id: entry.id,\n      ...(entry.description !== undefined ? { description: entry.description } : {}),\n      ...(entry.tags !== undefined ? { tags: entry.tags } : {}),\n    });\n  }\n\n  size(): number {\n    return this.#entries.size;\n  }\n}\n"],"mappings":";;;;;;;;;;;AA8IA,IAAa,gBAAb,MAA2B;CACzB,CAASA,0BAAoC,IAAI,KAAK;CAEtD,SAAS,OAAgC;AACvC,QAAKA,QAAS,IAAI,MAAM,IAAI;GAC1B,IAAI,MAAM;GACV,OAAO,MAAM;GACb,GAAI,MAAM,gBAAgB,SAAY,EAAE,aAAa,MAAM,aAAa,GAAG,EAAE;GAC7E,GAAI,MAAM,SAAS,SAAY,EAAE,MAAM,OAAO,OAAO,MAAM,KAAK,OAAO,CAAC,EAAE,GAAG,EAAE;GAChF,CAAC;;CAGJ,WAAW,IAAqB;AAC9B,SAAO,MAAKA,QAAS,OAAO,GAAG;;CAGjC,IAAI,IAAyC;AAC3C,SAAO,MAAKA,QAAS,IAAI,GAAG,EAAE;;CAGhC,IAAI,IAAqB;AACvB,SAAO,MAAKA,QAAS,IAAI,GAAG;;CAG9B,OAAoC;AAClC,SAAO,OAAO,OACZ,CAAC,GAAG,MAAKA,QAAS,QAAQ,CAAC,CAAC,KAAK,UAC/B,OAAO,OAAO;GACZ,IAAI,MAAM;GACV,GAAI,MAAM,gBAAgB,SAAY,EAAE,aAAa,MAAM,aAAa,GAAG,EAAE;GAC7E,GAAI,MAAM,SAAS,SAAY,EAAE,MAAM,MAAM,MAAM,GAAG,EAAE;GACzD,CAAC,CACH,CACF;;CAGH,SAAS,IAAsC;EAC7C,MAAM,QAAQ,MAAKA,QAAS,IAAI,GAAG;AACnC,MAAI,UAAU,OAAW,QAAO;AAChC,SAAO,OAAO,OAAO;GACnB,IAAI,MAAM;GACV,GAAI,MAAM,gBAAgB,SAAY,EAAE,aAAa,MAAM,aAAa,GAAG,EAAE;GAC7E,GAAI,MAAM,SAAS,SAAY,EAAE,MAAM,MAAM,MAAM,GAAG,EAAE;GACzD,CAAC;;CAGJ,OAAe;AACb,SAAO,MAAKA,QAAS;;;;;;AAOzB,IAAa,mBAAb,MAA8B;CAC5B,CAASA,0BAAuC,IAAI,KAAK;CAEzD,SAAS,OAAmC;AAC1C,QAAKA,QAAS,IAAI,MAAM,IAAI;GAC1B,IAAI,MAAM;GACV,UAAU,MAAM;GAChB,GAAI,MAAM,gBAAgB,SAAY,EAAE,aAAa,MAAM,aAAa,GAAG,EAAE;GAC7E,GAAI,MAAM,SAAS,SAAY,EAAE,MAAM,OAAO,OAAO,MAAM,KAAK,OAAO,CAAC,EAAE,GAAG,EAAE;GAChF,CAAC;;CAGJ,WAAW,IAAqB;AAC9B,SAAO,MAAKA,QAAS,OAAO,GAAG;;CAGjC,IAAI,IAA4C;AAC9C,SAAO,MAAKA,QAAS,IAAI,GAAG,EAAE;;CAGhC,IAAI,IAAqB;AACvB,SAAO,MAAKA,QAAS,IAAI,GAAG;;CAG9B,OAAuC;AACrC,SAAO,OAAO,OACZ,CAAC,GAAG,MAAKA,QAAS,QAAQ,CAAC,CAAC,KAAK,UAC/B,OAAO,OAAO;GACZ,IAAI,MAAM;GACV,GAAI,MAAM,gBAAgB,SAAY,EAAE,aAAa,MAAM,aAAa,GAAG,EAAE;GAC7E,GAAI,MAAM,SAAS,SAAY,EAAE,MAAM,MAAM,MAAM,GAAG,EAAE;GACzD,CAAC,CACH,CACF;;CAGH,SAAS,IAAyC;EAChD,MAAM,QAAQ,MAAKA,QAAS,IAAI,GAAG;AACnC,MAAI,UAAU,OAAW,QAAO;AAChC,SAAO,OAAO,OAAO;GACnB,IAAI,MAAM;GACV,GAAI,MAAM,gBAAgB,SAAY,EAAE,aAAa,MAAM,aAAa,GAAG,EAAE;GAC7E,GAAI,MAAM,SAAS,SAAY,EAAE,MAAM,MAAM,MAAM,GAAG,EAAE;GACzD,CAAC;;CAGJ,OAAe;AACb,SAAO,MAAKA,QAAS"}

package/dist/replay/index.d.ts

@@ -0,0 +1,2 @@
+import { ReplayApi, ReplayMode, ReplayResponse, ReplayRoutesDeps, createReplayRoutes } from "./routes.js";
+export { type ReplayApi, type ReplayMode, type ReplayResponse, type ReplayRoutesDeps, createReplayRoutes };

package/dist/replay/index.js

@@ -0,0 +1,3 @@
+import { createReplayRoutes } from "./routes.js";
+
+export { createReplayRoutes };

package/dist/replay/routes.d.ts

@@ -0,0 +1,46 @@
+import { ServerVariables } from "../internal/context.js";
+import { AuditDb } from "@graphorin/security/audit";
+import { Hono } from "hono";
+
+//#region src/replay/routes.d.ts
+
+/** @stable */
+type ReplayMode = 'sanitized' | 'raw';
+/** @stable */
+interface ReplayApi {
+  loadRunReplay(input: {
+    readonly runId: string;
+    readonly mode: ReplayMode;
+    readonly fromMessageId?: string;
+    readonly provider?: string;
+  }): Promise<ReplayResponse>;
+  loadSessionReplay(input: {
+    readonly sessionId: string;
+    readonly mode: ReplayMode;
+    readonly fromMessageId?: string;
+    readonly provider?: string;
+  }): Promise<ReplayResponse>;
+}
+/** @stable */
+interface ReplayResponse {
+  readonly events: ReadonlyArray<unknown>;
+  readonly truncated?: boolean;
+  readonly nextCursor?: string;
+}
+/**
+ * @stable
+ */
+interface ReplayRoutesDeps {
+  readonly replay: ReplayApi;
+  readonly auditDb?: AuditDb;
+  readonly now?: () => number;
+}
+/**
+ * @stable
+ */
+declare function createReplayRoutes(deps: ReplayRoutesDeps): Hono<{
+  Variables: ServerVariables;
+}>;
+//#endregion
+export { ReplayApi, ReplayMode, ReplayResponse, ReplayRoutesDeps, createReplayRoutes };
+//# sourceMappingURL=routes.d.ts.map

package/dist/replay/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","names":[],"sources":["../../src/replay/routes.ts"],"sourcesContent":[],"mappings":";;;;;;;KA+BY,UAAA;;UAGK,SAAA;;;mBAGE;;;MAGb,QAAQ;;;mBAGK;;;MAGb,QAAQ;;;UAIG,cAAA;mBACE;;;;;;;UAoBF,gBAAA;mBACE;qBACE;;;;;;iBAOL,kBAAA,OAAyB,mBAAmB;aAAkB"}

package/dist/replay/routes.js

@@ -0,0 +1,189 @@
+import { appendAudit } from "@graphorin/security/audit";
+import { Hono } from "hono";
+import { z } from "zod";
+import { parseScope, scopeMatches } from "@graphorin/security/auth";
+
+//#region src/replay/routes.ts
+/**
+* Replay endpoints with scope enforcement.
+*
+*   POST   /v1/runs/:runId/replay
+*   POST   /v1/sessions/:id/replay
+*
+* Scope rules:
+*   - `raw: false` (default) → require `traces:read:sanitized`.
+*   - `raw: true`            → require `traces:read:raw` (admin).
+*
+* Every successful invocation appends a `trace.replay.accessed` audit
+* entry. The audit write is best-effort: a missing `AuditDb` does not
+* block the replay.
+*
+* The actual replay stream is consumer-supplied — the framework
+* accepts a `ReplayApi` from the operator that knows how to load
+* trace events for a `runId` / `sessionId`. Phase 14c only owns the
+* scope check + audit + transport.
+*
+* @packageDocumentation
+*/
+const SCOPE_SANITIZED = parseScope("traces:read:sanitized");
+const SCOPE_RAW = parseScope("traces:read:raw");
+const ReplayRequestSchema = z.object({
+	raw: z.boolean().optional(),
+	fromMessageId: z.string().min(1).optional(),
+	provider: z.string().min(1).optional()
+}).strict().default({});
+/**
+* @stable
+*/
+function createReplayRoutes(deps) {
+	const app = new Hono();
+	const now = deps.now ?? Date.now;
+	app.post("/runs/:runId/replay", async (c) => {
+		const runId = c.req.param("runId");
+		const body = ReplayRequestSchema.safeParse(await safelyParseJson(c));
+		if (!body.success) return c.json(buildValidationError("Invalid replay body.", body.error.issues), 400);
+		const mode = body.data.raw === true ? "raw" : "sanitized";
+		const auth = c.get("state").auth;
+		const scopeError = enforceReplayScope(auth, mode);
+		if (scopeError !== void 0) {
+			await maybeAppendAudit(deps.auditDb, {
+				actor: auditActor(auth),
+				action: "replay:skipped",
+				target: `run:${runId}`,
+				decision: "denied",
+				ts: now(),
+				metadata: {
+					mode,
+					reason: scopeError.code
+				}
+			});
+			return c.json(scopeError.body, scopeError.status);
+		}
+		const replay = await deps.replay.loadRunReplay({
+			runId,
+			mode,
+			...body.data.fromMessageId !== void 0 ? { fromMessageId: body.data.fromMessageId } : {},
+			...body.data.provider !== void 0 ? { provider: body.data.provider } : {}
+		});
+		await maybeAppendAudit(deps.auditDb, {
+			actor: auditActor(auth),
+			action: "replay:accessed",
+			target: `run:${runId}`,
+			decision: "success",
+			ts: now(),
+			metadata: {
+				mode,
+				eventCount: replay.events.length
+			}
+		});
+		return c.json(serializeReplay(replay, mode));
+	});
+	app.post("/sessions/:id/replay", async (c) => {
+		const sessionId = c.req.param("id");
+		const body = ReplayRequestSchema.safeParse(await safelyParseJson(c));
+		if (!body.success) return c.json(buildValidationError("Invalid replay body.", body.error.issues), 400);
+		const mode = body.data.raw === true ? "raw" : "sanitized";
+		const auth = c.get("state").auth;
+		const scopeError = enforceReplayScope(auth, mode);
+		if (scopeError !== void 0) {
+			await maybeAppendAudit(deps.auditDb, {
+				actor: auditActor(auth),
+				action: "replay:skipped",
+				target: `session:${sessionId}`,
+				decision: "denied",
+				ts: now(),
+				metadata: {
+					mode,
+					reason: scopeError.code
+				}
+			});
+			return c.json(scopeError.body, scopeError.status);
+		}
+		const replay = await deps.replay.loadSessionReplay({
+			sessionId,
+			mode,
+			...body.data.fromMessageId !== void 0 ? { fromMessageId: body.data.fromMessageId } : {},
+			...body.data.provider !== void 0 ? { provider: body.data.provider } : {}
+		});
+		await maybeAppendAudit(deps.auditDb, {
+			actor: auditActor(auth),
+			action: "replay:accessed",
+			target: `session:${sessionId}`,
+			decision: "success",
+			ts: now(),
+			metadata: {
+				mode,
+				eventCount: replay.events.length
+			}
+		});
+		return c.json(serializeReplay(replay, mode));
+	});
+	return app;
+}
+function enforceReplayScope(auth, mode) {
+	if (auth.kind === "unauthenticated") return {
+		code: "auth-required",
+		status: 401,
+		body: {
+			error: "auth-required",
+			message: "Authentication required for replay endpoints."
+		}
+	};
+	const required = mode === "raw" ? SCOPE_RAW : SCOPE_SANITIZED;
+	for (const scope of auth.grantedScopes) if (scopeMatches(scope, required)) return void 0;
+	return {
+		code: "scope-denied",
+		status: 403,
+		body: {
+			error: "scope-denied",
+			message: `Token lacks required scope '${required.raw}'.`,
+			hint: `Mint a token with the '${required.raw}' (or admin:*) scope.`
+		}
+	};
+}
+function auditActor(auth) {
+	if (auth.kind === "token") return {
+		kind: "token",
+		id: auth.token.tokenId,
+		...auth.token.label !== void 0 ? { label: auth.token.label } : {}
+	};
+	return {
+		kind: "system",
+		id: auth.kind === "anonymous" ? "anonymous" : "unauthenticated"
+	};
+}
+async function maybeAppendAudit(auditDb, entry) {
+	if (auditDb === void 0) return;
+	try {
+		await appendAudit(auditDb, entry);
+	} catch {}
+}
+function serializeReplay(replay, mode) {
+	return {
+		mode,
+		events: [...replay.events],
+		...replay.truncated === true ? { truncated: true } : {},
+		...replay.nextCursor !== void 0 ? { nextCursor: replay.nextCursor } : {}
+	};
+}
+function buildValidationError(message, issues) {
+	return {
+		error: "config-invalid",
+		message,
+		issues: issues.map((i) => ({
+			path: i.path,
+			message: i.message
+		}))
+	};
+}
+async function safelyParseJson(c) {
+	try {
+		return await c.req.json();
+	} catch {
+		return {};
+	}
+}
+
+//#endregion
+export { createReplayRoutes };
+//# sourceMappingURL=routes.js.map

package/dist/replay/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","names":["SCOPE_SANITIZED: ParsedScope","SCOPE_RAW: ParsedScope","mode: ReplayMode"],"sources":["../../src/replay/routes.ts"],"sourcesContent":["/**\n * Replay endpoints with scope enforcement.\n *\n *   POST   /v1/runs/:runId/replay\n *   POST   /v1/sessions/:id/replay\n *\n * Scope rules:\n *   - `raw: false` (default) → require `traces:read:sanitized`.\n *   - `raw: true`            → require `traces:read:raw` (admin).\n *\n * Every successful invocation appends a `trace.replay.accessed` audit\n * entry. The audit write is best-effort: a missing `AuditDb` does not\n * block the replay.\n *\n * The actual replay stream is consumer-supplied — the framework\n * accepts a `ReplayApi` from the operator that knows how to load\n * trace events for a `runId` / `sessionId`. Phase 14c only owns the\n * scope check + audit + transport.\n *\n * @packageDocumentation\n */\n\nimport { type AuditDb, appendAudit } from '@graphorin/security/audit';\nimport { type ParsedScope, parseScope, scopeMatches } from '@graphorin/security/auth';\nimport { Hono } from 'hono';\nimport type { ContentfulStatusCode } from 'hono/utils/http-status';\nimport { z } from 'zod';\n\nimport type { AuthState, ServerVariables } from '../internal/context.js';\n\n/** @stable */\nexport type ReplayMode = 'sanitized' | 'raw';\n\n/** @stable */\nexport interface ReplayApi {\n  loadRunReplay(input: {\n    readonly runId: string;\n    readonly mode: ReplayMode;\n    readonly fromMessageId?: string;\n    readonly provider?: string;\n  }): Promise<ReplayResponse>;\n  loadSessionReplay(input: {\n    readonly sessionId: string;\n    readonly mode: ReplayMode;\n    readonly fromMessageId?: string;\n    readonly provider?: string;\n  }): Promise<ReplayResponse>;\n}\n\n/** @stable */\nexport interface ReplayResponse {\n  readonly events: ReadonlyArray<unknown>;\n  readonly truncated?: boolean;\n  readonly nextCursor?: string;\n}\n\nconst SCOPE_SANITIZED: ParsedScope = parseScope('traces:read:sanitized');\nconst SCOPE_RAW: ParsedScope = parseScope('traces:read:raw');\n\nconst ReplayRequestSchema = z\n  .object({\n    raw: z.boolean().optional(),\n    fromMessageId: z.string().min(1).optional(),\n    provider: z.string().min(1).optional(),\n  })\n  .strict()\n  .default({});\n\n/**\n * @stable\n */\nexport interface ReplayRoutesDeps {\n  readonly replay: ReplayApi;\n  readonly auditDb?: AuditDb;\n  readonly now?: () => number;\n}\n\n/**\n * @stable\n */\nexport function createReplayRoutes(deps: ReplayRoutesDeps): Hono<{ Variables: ServerVariables }> {\n  const app = new Hono<{ Variables: ServerVariables }>();\n  const now = deps.now ?? Date.now;\n\n  app.post('/runs/:runId/replay', async (c) => {\n    const runId = c.req.param('runId');\n    const body = ReplayRequestSchema.safeParse(await safelyParseJson(c));\n    if (!body.success) {\n      return c.json(buildValidationError('Invalid replay body.', body.error.issues), 400);\n    }\n    const mode: ReplayMode = body.data.raw === true ? 'raw' : 'sanitized';\n    const auth = c.get('state').auth;\n    const scopeError = enforceReplayScope(auth, mode);\n    if (scopeError !== undefined) {\n      await maybeAppendAudit(deps.auditDb, {\n        actor: auditActor(auth),\n        action: 'replay:skipped',\n        target: `run:${runId}`,\n        decision: 'denied',\n        ts: now(),\n        metadata: { mode, reason: scopeError.code },\n      });\n      return c.json(scopeError.body, scopeError.status);\n    }\n    const replay = await deps.replay.loadRunReplay({\n      runId,\n      mode,\n      ...(body.data.fromMessageId !== undefined ? { fromMessageId: body.data.fromMessageId } : {}),\n      ...(body.data.provider !== undefined ? { provider: body.data.provider } : {}),\n    });\n    await maybeAppendAudit(deps.auditDb, {\n      actor: auditActor(auth),\n      action: 'replay:accessed',\n      target: `run:${runId}`,\n      decision: 'success',\n      ts: now(),\n      metadata: { mode, eventCount: replay.events.length },\n    });\n    return c.json(serializeReplay(replay, mode));\n  });\n\n  app.post('/sessions/:id/replay', async (c) => {\n    const sessionId = c.req.param('id');\n    const body = ReplayRequestSchema.safeParse(await safelyParseJson(c));\n    if (!body.success) {\n      return c.json(buildValidationError('Invalid replay body.', body.error.issues), 400);\n    }\n    const mode: ReplayMode = body.data.raw === true ? 'raw' : 'sanitized';\n    const auth = c.get('state').auth;\n    const scopeError = enforceReplayScope(auth, mode);\n    if (scopeError !== undefined) {\n      await maybeAppendAudit(deps.auditDb, {\n        actor: auditActor(auth),\n        action: 'replay:skipped',\n        target: `session:${sessionId}`,\n        decision: 'denied',\n        ts: now(),\n        metadata: { mode, reason: scopeError.code },\n      });\n      return c.json(scopeError.body, scopeError.status);\n    }\n    const replay = await deps.replay.loadSessionReplay({\n      sessionId,\n      mode,\n      ...(body.data.fromMessageId !== undefined ? { fromMessageId: body.data.fromMessageId } : {}),\n      ...(body.data.provider !== undefined ? { provider: body.data.provider } : {}),\n    });\n    await maybeAppendAudit(deps.auditDb, {\n      actor: auditActor(auth),\n      action: 'replay:accessed',\n      target: `session:${sessionId}`,\n      decision: 'success',\n      ts: now(),\n      metadata: { mode, eventCount: replay.events.length },\n    });\n    return c.json(serializeReplay(replay, mode));\n  });\n\n  return app;\n}\n\ninterface ScopeRefusal {\n  readonly code: 'auth-required' | 'scope-denied';\n  readonly status: ContentfulStatusCode;\n  readonly body: { readonly error: string; readonly message: string; readonly hint?: string };\n}\n\nfunction enforceReplayScope(auth: AuthState, mode: ReplayMode): ScopeRefusal | undefined {\n  // IP-13: both a verified token and the no-auth anonymous principal carry a\n  // `grantedScopes` set; only a genuinely unauthenticated request is refused.\n  if (auth.kind === 'unauthenticated') {\n    return {\n      code: 'auth-required',\n      status: 401,\n      body: {\n        error: 'auth-required',\n        message: 'Authentication required for replay endpoints.',\n      },\n    };\n  }\n  const required = mode === 'raw' ? SCOPE_RAW : SCOPE_SANITIZED;\n  for (const scope of auth.grantedScopes) {\n    if (scopeMatches(scope, required)) return undefined;\n  }\n  return {\n    code: 'scope-denied',\n    status: 403,\n    body: {\n      error: 'scope-denied',\n      message: `Token lacks required scope '${required.raw}'.`,\n      hint: `Mint a token with the '${required.raw}' (or admin:*) scope.`,\n    },\n  };\n}\n\nfunction auditActor(auth: AuthState): {\n  readonly kind: 'token' | 'system';\n  readonly id: string;\n  readonly label?: string;\n} {\n  if (auth.kind === 'token') {\n    return {\n      kind: 'token',\n      id: auth.token.tokenId,\n      ...(auth.token.label !== undefined ? { label: auth.token.label } : {}),\n    };\n  }\n  // IP-13: attribute no-auth replays to the synthetic 'anonymous' principal.\n  return { kind: 'system', id: auth.kind === 'anonymous' ? 'anonymous' : 'unauthenticated' };\n}\n\nasync function maybeAppendAudit(\n  auditDb: AuditDb | undefined,\n  entry: Parameters<typeof appendAudit>[1],\n): Promise<void> {\n  if (auditDb === undefined) return;\n  try {\n    await appendAudit(auditDb, entry);\n  } catch {\n    // Best-effort — replay must not be blocked by audit failures.\n  }\n}\n\nfunction serializeReplay(replay: ReplayResponse, mode: ReplayMode): Record<string, unknown> {\n  return {\n    mode,\n    events: [...replay.events],\n    ...(replay.truncated === true ? { truncated: true } : {}),\n    ...(replay.nextCursor !== undefined ? { nextCursor: replay.nextCursor } : {}),\n  };\n}\n\nfunction buildValidationError(\n  message: string,\n  issues: ReadonlyArray<{\n    readonly path: ReadonlyArray<string | number>;\n    readonly message: string;\n  }>,\n): Record<string, unknown> {\n  return {\n    error: 'config-invalid',\n    message,\n    issues: issues.map((i) => ({ path: i.path, message: i.message })),\n  };\n}\n\nasync function safelyParseJson(c: {\n  readonly req: { readonly json: () => Promise<unknown> };\n}): Promise<unknown> {\n  try {\n    return await c.req.json();\n  } catch {\n    return {};\n  }\n}\n"],"mappings":"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"}

package/dist/routes/agents.d.ts

@@ -0,0 +1,41 @@
+import { ServerVariables } from "../internal/context.js";
+import { AgentRegistry } from "../registry/index.js";
+import { WsDispatcher } from "../ws/dispatcher.js";
+import { RunStateTracker } from "../runtime/run-state.js";
+import { Hono } from "hono";
+
+//#region src/routes/agents.d.ts
+
+/**
+ * @stable
+ */
+interface AgentRoutesDeps {
+  readonly agents: AgentRegistry;
+  readonly runs: RunStateTracker;
+  readonly newRunId?: () => string;
+  /**
+   * Streaming dispatcher (IP-2). When present, `POST /:id/stream`
+   * actually runs the agent and emits every event onto the
+   * `agent:<id>/runs/<runId>/events` subject.
+   */
+  readonly dispatcher?: WsDispatcher;
+}
+/**
+ * @stable
+ */
+declare function createAgentRoutes(deps: AgentRoutesDeps): Hono<{
+  Variables: ServerVariables;
+}>;
+/**
+ * Companion router for the `/runs/...` surface. Kept separate so the
+ * `createServer` factory can mount it under the top-level base path
+ * rather than under `/agents`.
+ *
+ * @stable
+ */
+declare function createRunRoutes(deps: AgentRoutesDeps): Hono<{
+  Variables: ServerVariables;
+}>;
+//#endregion
+export { AgentRoutesDeps, createAgentRoutes, createRunRoutes };
+//# sourceMappingURL=agents.d.ts.map

package/dist/routes/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","names":[],"sources":["../../src/routes/agents.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;UA8BiB,eAAA;mBACE;iBACF;;;;;;;wBAAe;;;;;iBAsBhB,iBAAA,OAAwB,kBAAkB;aAAkB;;;;;;;;;iBA+L5D,eAAA,OAAsB,kBAAkB;aAAkB"}