@graphorin/server 0.5.0

package/dist/routes/skills.js

@@ -0,0 +1,54 @@
+import { createScopeMiddleware } from "../middleware/scope.js";
+import { Hono } from "hono";
+import { z } from "zod";
+
+//#region src/routes/skills.ts
+const InstallBodySchema = z.object({
+	source: z.string().min(1),
+	trust: z.enum(["verified", "unverified"]).optional()
+}).strict();
+/**
+* @stable
+*/
+function createSkillsRoutes(deps) {
+	const app = new Hono();
+	app.get("/", createScopeMiddleware("skills:read"), async (c) => {
+		return c.json({ skills: await deps.skills.list() });
+	});
+	app.get("/:name", createScopeMiddleware("skills:read"), async (c) => {
+		const name = c.req.param("name");
+		const skill = await deps.skills.get(name);
+		if (skill === null) return c.json({
+			error: "skill-not-found",
+			message: `Skill '${name}' not found.`
+		}, 404);
+		return c.json({ skill });
+	});
+	app.post("/install", createScopeMiddleware("skills:install"), async (c) => {
+		const parsed = InstallBodySchema.safeParse(await safelyParseJson(c));
+		if (!parsed.success) return c.json({
+			error: "config-invalid",
+			message: "Invalid install body.",
+			issues: parsed.error.issues.map((i) => ({
+				path: i.path,
+				message: i.message
+			}))
+		}, 400);
+		const installInput = { source: parsed.data.source };
+		if (parsed.data.trust !== void 0) installInput.trust = parsed.data.trust;
+		const out = await deps.skills.install(installInput);
+		return c.json({ skill: out }, 201);
+	});
+	return app;
+}
+async function safelyParseJson(c) {
+	try {
+		return await c.req.json();
+	} catch {
+		return {};
+	}
+}
+
+//#endregion
+export { createSkillsRoutes };
+//# sourceMappingURL=skills.js.map

package/dist/routes/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","names":["installInput: { source: string; trust?: 'verified' | 'unverified' }"],"sources":["../../src/routes/skills.ts"],"sourcesContent":["/**\n * Skill REST routes.\n *\n *   GET    /skills                     (scope `skills:read`)\n *   POST   /skills/install             (idempotent; scope `skills:install`)\n *   GET    /skills/:name               (scope `skills:read`)\n *\n * @packageDocumentation\n */\n\nimport type { Context } from 'hono';\nimport { Hono } from 'hono';\nimport { z } from 'zod';\n\nimport type { ServerVariables } from '../internal/context.js';\nimport { createScopeMiddleware } from '../middleware/scope.js';\n\n/**\n * @stable\n */\nexport interface SkillsApi {\n  list(): Promise<ReadonlyArray<{ readonly name: string; readonly version?: string }>>;\n  get(name: string): Promise<unknown | null>;\n  install(input: {\n    readonly source: string;\n    readonly trust?: 'verified' | 'unverified';\n  }): Promise<unknown>;\n}\n\nconst InstallBodySchema = z\n  .object({\n    source: z.string().min(1),\n    trust: z.enum(['verified', 'unverified']).optional(),\n  })\n  .strict();\n\n/**\n * @stable\n */\nexport interface SkillsRoutesDeps {\n  readonly skills: SkillsApi;\n}\n\n/**\n * @stable\n */\nexport function createSkillsRoutes(deps: SkillsRoutesDeps): Hono<{ Variables: ServerVariables }> {\n  const app = new Hono<{ Variables: ServerVariables }>();\n\n  app.get('/', createScopeMiddleware('skills:read'), async (c) => {\n    return c.json({ skills: await deps.skills.list() });\n  });\n\n  app.get('/:name', createScopeMiddleware('skills:read'), async (c) => {\n    const name = c.req.param('name');\n    const skill = await deps.skills.get(name);\n    if (skill === null)\n      return c.json({ error: 'skill-not-found', message: `Skill '${name}' not found.` }, 404);\n    return c.json({ skill });\n  });\n\n  app.post('/install', createScopeMiddleware('skills:install'), async (c) => {\n    const parsed = InstallBodySchema.safeParse(await safelyParseJson(c));\n    if (!parsed.success) {\n      return c.json(\n        {\n          error: 'config-invalid',\n          message: 'Invalid install body.',\n          issues: parsed.error.issues.map((i) => ({ path: i.path, message: i.message })),\n        },\n        400,\n      );\n    }\n    const installInput: { source: string; trust?: 'verified' | 'unverified' } = {\n      source: parsed.data.source,\n    };\n    if (parsed.data.trust !== undefined) installInput.trust = parsed.data.trust;\n    const out = await deps.skills.install(installInput);\n    return c.json({ skill: out }, 201);\n  });\n\n  return app;\n}\n\nasync function safelyParseJson(c: Context<{ Variables: ServerVariables }>): Promise<unknown> {\n  try {\n    return await c.req.json();\n  } catch {\n    return {};\n  }\n}\n"],"mappings":";;;;;AA6BA,MAAM,oBAAoB,EACvB,OAAO;CACN,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE;CACzB,OAAO,EAAE,KAAK,CAAC,YAAY,aAAa,CAAC,CAAC,UAAU;CACrD,CAAC,CACD,QAAQ;;;;AAYX,SAAgB,mBAAmB,MAA8D;CAC/F,MAAM,MAAM,IAAI,MAAsC;AAEtD,KAAI,IAAI,KAAK,sBAAsB,cAAc,EAAE,OAAO,MAAM;AAC9D,SAAO,EAAE,KAAK,EAAE,QAAQ,MAAM,KAAK,OAAO,MAAM,EAAE,CAAC;GACnD;AAEF,KAAI,IAAI,UAAU,sBAAsB,cAAc,EAAE,OAAO,MAAM;EACnE,MAAM,OAAO,EAAE,IAAI,MAAM,OAAO;EAChC,MAAM,QAAQ,MAAM,KAAK,OAAO,IAAI,KAAK;AACzC,MAAI,UAAU,KACZ,QAAO,EAAE,KAAK;GAAE,OAAO;GAAmB,SAAS,UAAU,KAAK;GAAe,EAAE,IAAI;AACzF,SAAO,EAAE,KAAK,EAAE,OAAO,CAAC;GACxB;AAEF,KAAI,KAAK,YAAY,sBAAsB,iBAAiB,EAAE,OAAO,MAAM;EACzE,MAAM,SAAS,kBAAkB,UAAU,MAAM,gBAAgB,EAAE,CAAC;AACpE,MAAI,CAAC,OAAO,QACV,QAAO,EAAE,KACP;GACE,OAAO;GACP,SAAS;GACT,QAAQ,OAAO,MAAM,OAAO,KAAK,OAAO;IAAE,MAAM,EAAE;IAAM,SAAS,EAAE;IAAS,EAAE;GAC/E,EACD,IACD;EAEH,MAAMA,eAAsE,EAC1E,QAAQ,OAAO,KAAK,QACrB;AACD,MAAI,OAAO,KAAK,UAAU,OAAW,cAAa,QAAQ,OAAO,KAAK;EACtE,MAAM,MAAM,MAAM,KAAK,OAAO,QAAQ,aAAa;AACnD,SAAO,EAAE,KAAK,EAAE,OAAO,KAAK,EAAE,IAAI;GAClC;AAEF,QAAO;;AAGT,eAAe,gBAAgB,GAA8D;AAC3F,KAAI;AACF,SAAO,MAAM,EAAE,IAAI,MAAM;SACnB;AACN,SAAO,EAAE"}

package/dist/routes/tokens.d.ts

@@ -0,0 +1,25 @@
+import { ServerVariables } from "../internal/context.js";
+import { SecretValue } from "@graphorin/security";
+import { Hono } from "hono";
+import { AuthTokenStore } from "@graphorin/core/contracts";
+
+//#region src/routes/tokens.d.ts
+
+/**
+ * @stable
+ */
+interface TokensRoutesDeps {
+  readonly tokenStore: AuthTokenStore;
+  readonly pepper: SecretValue;
+  readonly defaultEnv: string;
+  readonly allowedEnvs: ReadonlyArray<string>;
+}
+/**
+ * @stable
+ */
+declare function createTokensRoutes(deps: TokensRoutesDeps): Hono<{
+  Variables: ServerVariables;
+}>;
+//#endregion
+export { TokensRoutesDeps, createTokensRoutes };
+//# sourceMappingURL=tokens.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","names":[],"sources":["../../src/routes/tokens.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AAwCgE,UAnB/C,gBAAA,CAmB+C;uBAlBzC;mBACJ;;wBAEK;;;;;iBAeR,kBAAA,OAAyB,mBAAmB;aAAkB"}

package/dist/routes/tokens.js

@@ -0,0 +1,87 @@
+import { createScopeMiddleware } from "../middleware/scope.js";
+import { createToken, listTokens, revokeToken } from "@graphorin/security";
+import { Hono } from "hono";
+import { z } from "zod";
+
+//#region src/routes/tokens.ts
+const CreateBodySchema = z.object({
+	label: z.string().min(1).optional(),
+	scopes: z.array(z.string().min(3)).min(1),
+	env: z.string().min(1).optional(),
+	expiresInMs: z.number().int().positive().optional()
+}).strict();
+/**
+* @stable
+*/
+function createTokensRoutes(deps) {
+	const app = new Hono();
+	app.get("/", createScopeMiddleware("tokens:list"), async (c) => {
+		const sanitized = (await listTokens(deps.tokenStore)).map((r) => ({
+			id: r.id,
+			label: r.label,
+			scopes: r.scopes,
+			createdAt: r.createdAt,
+			lastUsedAt: r.lastUsedAt,
+			expiresAt: r.expiresAt,
+			revokedAt: r.revokedAt
+		}));
+		return c.json({ tokens: sanitized });
+	});
+	app.post("/", createScopeMiddleware("tokens:create"), async (c) => {
+		const parsed = CreateBodySchema.safeParse(await safelyParseJson(c));
+		if (!parsed.success) return c.json({
+			error: "config-invalid",
+			message: "Invalid create-token body.",
+			issues: parsed.error.issues.map((i) => ({
+				path: i.path,
+				message: i.message
+			}))
+		}, 400);
+		const env = parsed.data.env ?? deps.defaultEnv;
+		if (!deps.allowedEnvs.includes(env)) return c.json({
+			error: "config-invalid",
+			message: `Environment '${env}' is not in the allowed set.`,
+			allowed: deps.allowedEnvs
+		}, 400);
+		const created = await createToken({
+			tokenStore: deps.tokenStore,
+			pepper: deps.pepper,
+			env,
+			scopes: parsed.data.scopes,
+			...parsed.data.label !== void 0 ? { label: parsed.data.label } : {},
+			...parsed.data.expiresInMs !== void 0 ? { expiresInMs: parsed.data.expiresInMs } : {}
+		});
+		const raw = await created.raw.use((value) => value);
+		return c.json({
+			token: {
+				id: created.record.id,
+				label: created.record.label,
+				scopes: created.record.scopes,
+				createdAt: created.record.createdAt,
+				expiresAt: created.record.expiresAt
+			},
+			raw,
+			warning: "Store this raw value securely; it is shown exactly once."
+		}, 201);
+	});
+	app.delete("/:id", createScopeMiddleware("tokens:revoke"), async (c) => {
+		const id = c.req.param("id");
+		if (await revokeToken(deps.tokenStore, id) === void 0) return c.json({
+			error: "token-not-found",
+			message: `Token '${id}' not found.`
+		}, 404);
+		return c.body(null, 204);
+	});
+	return app;
+}
+async function safelyParseJson(c) {
+	try {
+		return await c.req.json();
+	} catch {
+		return {};
+	}
+}
+
+//#endregion
+export { createTokensRoutes };
+//# sourceMappingURL=tokens.js.map

package/dist/routes/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","names":[],"sources":["../../src/routes/tokens.ts"],"sourcesContent":["/**\n * Token-management REST routes. The handlers wrap the\n * `@graphorin/security/auth` CRUD library functions so the operator\n * can mint / list / revoke tokens through the same API surface as\n * `graphorin token` (Phase 15).\n *\n * @packageDocumentation\n */\n\nimport type { AuthTokenStore } from '@graphorin/core/contracts';\nimport { createToken, listTokens, revokeToken, type SecretValue } from '@graphorin/security';\nimport type { Context } from 'hono';\nimport { Hono } from 'hono';\nimport { z } from 'zod';\n\nimport type { ServerVariables } from '../internal/context.js';\nimport { createScopeMiddleware } from '../middleware/scope.js';\n\n/**\n * @stable\n */\nexport interface TokensRoutesDeps {\n  readonly tokenStore: AuthTokenStore;\n  readonly pepper: SecretValue;\n  readonly defaultEnv: string;\n  readonly allowedEnvs: ReadonlyArray<string>;\n}\n\nconst CreateBodySchema = z\n  .object({\n    label: z.string().min(1).optional(),\n    scopes: z.array(z.string().min(3)).min(1),\n    env: z.string().min(1).optional(),\n    expiresInMs: z.number().int().positive().optional(),\n  })\n  .strict();\n\n/**\n * @stable\n */\nexport function createTokensRoutes(deps: TokensRoutesDeps): Hono<{ Variables: ServerVariables }> {\n  const app = new Hono<{ Variables: ServerVariables }>();\n\n  app.get('/', createScopeMiddleware('tokens:list'), async (c) => {\n    const records = await listTokens(deps.tokenStore);\n    // Never reveal hashes or pepper-derived material.\n    const sanitized = records.map((r) => ({\n      id: r.id,\n      label: r.label,\n      scopes: r.scopes,\n      createdAt: r.createdAt,\n      lastUsedAt: r.lastUsedAt,\n      expiresAt: r.expiresAt,\n      revokedAt: r.revokedAt,\n    }));\n    return c.json({ tokens: sanitized });\n  });\n\n  app.post('/', createScopeMiddleware('tokens:create'), async (c) => {\n    const parsed = CreateBodySchema.safeParse(await safelyParseJson(c));\n    if (!parsed.success) {\n      return c.json(\n        {\n          error: 'config-invalid',\n          message: 'Invalid create-token body.',\n          issues: parsed.error.issues.map((i) => ({ path: i.path, message: i.message })),\n        },\n        400,\n      );\n    }\n    const env = parsed.data.env ?? deps.defaultEnv;\n    if (!deps.allowedEnvs.includes(env)) {\n      return c.json(\n        {\n          error: 'config-invalid',\n          message: `Environment '${env}' is not in the allowed set.`,\n          allowed: deps.allowedEnvs,\n        },\n        400,\n      );\n    }\n    const created = await createToken({\n      tokenStore: deps.tokenStore,\n      pepper: deps.pepper,\n      env,\n      scopes: parsed.data.scopes,\n      ...(parsed.data.label !== undefined ? { label: parsed.data.label } : {}),\n      ...(parsed.data.expiresInMs !== undefined ? { expiresInMs: parsed.data.expiresInMs } : {}),\n    });\n    // Reveal the raw token exactly once — at creation.\n    const raw = await created.raw.use((value) => value);\n    return c.json(\n      {\n        token: {\n          id: created.record.id,\n          label: created.record.label,\n          scopes: created.record.scopes,\n          createdAt: created.record.createdAt,\n          expiresAt: created.record.expiresAt,\n        },\n        raw,\n        warning: 'Store this raw value securely; it is shown exactly once.',\n      },\n      201,\n    );\n  });\n\n  app.delete('/:id', createScopeMiddleware('tokens:revoke'), async (c) => {\n    const id = c.req.param('id');\n    const updated = await revokeToken(deps.tokenStore, id);\n    if (updated === undefined) {\n      return c.json({ error: 'token-not-found', message: `Token '${id}' not found.` }, 404);\n    }\n    return c.body(null, 204);\n  });\n\n  return app;\n}\n\nasync function safelyParseJson(c: Context<{ Variables: ServerVariables }>): Promise<unknown> {\n  try {\n    return await c.req.json();\n  } catch {\n    return {};\n  }\n}\n"],"mappings":";;;;;;AA4BA,MAAM,mBAAmB,EACtB,OAAO;CACN,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,UAAU;CACnC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;CACzC,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,UAAU;CACjC,aAAa,EAAE,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU;CACpD,CAAC,CACD,QAAQ;;;;AAKX,SAAgB,mBAAmB,MAA8D;CAC/F,MAAM,MAAM,IAAI,MAAsC;AAEtD,KAAI,IAAI,KAAK,sBAAsB,cAAc,EAAE,OAAO,MAAM;EAG9D,MAAM,aAFU,MAAM,WAAW,KAAK,WAAW,EAEvB,KAAK,OAAO;GACpC,IAAI,EAAE;GACN,OAAO,EAAE;GACT,QAAQ,EAAE;GACV,WAAW,EAAE;GACb,YAAY,EAAE;GACd,WAAW,EAAE;GACb,WAAW,EAAE;GACd,EAAE;AACH,SAAO,EAAE,KAAK,EAAE,QAAQ,WAAW,CAAC;GACpC;AAEF,KAAI,KAAK,KAAK,sBAAsB,gBAAgB,EAAE,OAAO,MAAM;EACjE,MAAM,SAAS,iBAAiB,UAAU,MAAM,gBAAgB,EAAE,CAAC;AACnE,MAAI,CAAC,OAAO,QACV,QAAO,EAAE,KACP;GACE,OAAO;GACP,SAAS;GACT,QAAQ,OAAO,MAAM,OAAO,KAAK,OAAO;IAAE,MAAM,EAAE;IAAM,SAAS,EAAE;IAAS,EAAE;GAC/E,EACD,IACD;EAEH,MAAM,MAAM,OAAO,KAAK,OAAO,KAAK;AACpC,MAAI,CAAC,KAAK,YAAY,SAAS,IAAI,CACjC,QAAO,EAAE,KACP;GACE,OAAO;GACP,SAAS,gBAAgB,IAAI;GAC7B,SAAS,KAAK;GACf,EACD,IACD;EAEH,MAAM,UAAU,MAAM,YAAY;GAChC,YAAY,KAAK;GACjB,QAAQ,KAAK;GACb;GACA,QAAQ,OAAO,KAAK;GACpB,GAAI,OAAO,KAAK,UAAU,SAAY,EAAE,OAAO,OAAO,KAAK,OAAO,GAAG,EAAE;GACvE,GAAI,OAAO,KAAK,gBAAgB,SAAY,EAAE,aAAa,OAAO,KAAK,aAAa,GAAG,EAAE;GAC1F,CAAC;EAEF,MAAM,MAAM,MAAM,QAAQ,IAAI,KAAK,UAAU,MAAM;AACnD,SAAO,EAAE,KACP;GACE,OAAO;IACL,IAAI,QAAQ,OAAO;IACnB,OAAO,QAAQ,OAAO;IACtB,QAAQ,QAAQ,OAAO;IACvB,WAAW,QAAQ,OAAO;IAC1B,WAAW,QAAQ,OAAO;IAC3B;GACD;GACA,SAAS;GACV,EACD,IACD;GACD;AAEF,KAAI,OAAO,QAAQ,sBAAsB,gBAAgB,EAAE,OAAO,MAAM;EACtE,MAAM,KAAK,EAAE,IAAI,MAAM,KAAK;AAE5B,MADgB,MAAM,YAAY,KAAK,YAAY,GAAG,KACtC,OACd,QAAO,EAAE,KAAK;GAAE,OAAO;GAAmB,SAAS,UAAU,GAAG;GAAe,EAAE,IAAI;AAEvF,SAAO,EAAE,KAAK,MAAM,IAAI;GACxB;AAEF,QAAO;;AAGT,eAAe,gBAAgB,GAA8D;AAC3F,KAAI;AACF,SAAO,MAAM,EAAE,IAAI,MAAM;SACnB;AACN,SAAO,EAAE"}

package/dist/routes/workflows.d.ts

@@ -0,0 +1,27 @@
+import { ServerVariables } from "../internal/context.js";
+import { WorkflowRegistry } from "../registry/index.js";
+import { WsDispatcher } from "../ws/dispatcher.js";
+import { RunStateTracker } from "../runtime/run-state.js";
+import { Hono } from "hono";
+
+//#region src/routes/workflows.d.ts
+
+/**
+ * @stable
+ */
+interface WorkflowRoutesDeps {
+  readonly workflows: WorkflowRegistry;
+  readonly runs: RunStateTracker;
+  readonly newRunId?: () => string;
+  /** Streaming dispatcher (IP-2): workflow events reach the run subject. */
+  readonly dispatcher?: WsDispatcher;
+}
+/**
+ * @stable
+ */
+declare function createWorkflowRoutes(deps: WorkflowRoutesDeps): Hono<{
+  Variables: ServerVariables;
+}>;
+//#endregion
+export { WorkflowRoutesDeps, createWorkflowRoutes };
+//# sourceMappingURL=workflows.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.d.ts","names":[],"sources":["../../src/routes/workflows.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;UA0BiB,kBAAA;sBACK;iBACL;;;wBAAe;;;;;iBAiChB,oBAAA,OACR,qBACL;aAAkB"}

package/dist/routes/workflows.js

@@ -0,0 +1,220 @@
+import { WorkflowNotFoundError } from "../errors/index.js";
+import { createScopeMiddleware } from "../middleware/scope.js";
+import { newRequestId } from "../internal/ids.js";
+import { Hono } from "hono";
+import { z } from "zod";
+
+//#region src/routes/workflows.ts
+const ExecuteBodySchema = z.object({
+	input: z.unknown().optional(),
+	threadId: z.string().min(1).optional(),
+	sessionId: z.string().min(1).optional(),
+	userId: z.string().min(1).optional()
+}).strict().default({});
+const ResumeBodySchema = z.object({
+	threadId: z.string().min(1),
+	resume: z.unknown().optional()
+}).strict();
+const ForkBodySchema = z.object({
+	fromThreadId: z.string().min(1),
+	fromCheckpointId: z.string().min(1).optional()
+}).strict();
+/**
+* @stable
+*/
+function createWorkflowRoutes(deps) {
+	const app = new Hono();
+	const newRunId = deps.newRunId ?? newRequestId;
+	app.get("/", createScopeMiddleware("workflows:read"), (c) => c.json({ workflows: deps.workflows.list() }));
+	app.post("/:id/execute", createScopeMiddleware((_path, params) => `workflows:execute:${params.id}`), async (c) => {
+		const id = c.req.param("id");
+		const workflow = deps.workflows.get(id);
+		if (workflow === void 0) {
+			const err = new WorkflowNotFoundError(id);
+			return c.json({
+				error: err.kind,
+				message: err.message
+			}, 404);
+		}
+		const parsed = ExecuteBodySchema.safeParse(await safelyParseJson(c));
+		if (!parsed.success) return c.json({
+			error: "config-invalid",
+			message: "Invalid execute body.",
+			issues: parsed.error.issues.map((i) => ({
+				path: i.path,
+				message: i.message
+			}))
+		}, 400);
+		const runId = newRunId();
+		const tracker = deps.runs.start(runId, {
+			kind: "workflow",
+			workflowId: id,
+			...parsed.data.threadId !== void 0 ? { threadId: parsed.data.threadId } : {},
+			...parsed.data.sessionId !== void 0 ? { sessionId: parsed.data.sessionId } : {},
+			...parsed.data.userId !== void 0 ? { userId: parsed.data.userId } : {}
+		});
+		const subject = `workflow:${id}/runs/${runId}/events`;
+		backgroundExecute(workflow, parsed.data, tracker, deps.runs, runId, {
+			subject,
+			...deps.dispatcher !== void 0 ? { dispatcher: deps.dispatcher } : {}
+		});
+		return c.json({
+			runId,
+			status: "running",
+			subscribe: { websocket: subject }
+		}, 202);
+	});
+	app.post("/:id/resume", createScopeMiddleware((_path, params) => `workflows:resume:${params.id}`), async (c) => {
+		const id = c.req.param("id");
+		const workflow = deps.workflows.get(id);
+		if (workflow === void 0) {
+			const err = new WorkflowNotFoundError(id);
+			return c.json({
+				error: err.kind,
+				message: err.message
+			}, 404);
+		}
+		const parsed = ResumeBodySchema.safeParse(await safelyParseJson(c));
+		if (!parsed.success) return c.json({
+			error: "config-invalid",
+			message: "Invalid resume body.",
+			issues: parsed.error.issues.map((i) => ({
+				path: i.path,
+				message: i.message
+			}))
+		}, 400);
+		if (workflow.resume === void 0) return c.json({
+			error: "workflow-resume-unsupported",
+			message: `Workflow '${id}' does not implement resume().`
+		}, 400);
+		const runId = newRunId();
+		deps.runs.declare(runId, {
+			kind: "workflow",
+			workflowId: id,
+			threadId: parsed.data.threadId
+		});
+		return c.json({
+			runId,
+			threadId: parsed.data.threadId,
+			status: "pending",
+			subscribe: {
+				websocket: `workflow:${id}/runs/${runId}/events`,
+				sse: `/v1/runs/${runId}/events`
+			}
+		}, 202);
+	});
+	app.get("/:id/state", createScopeMiddleware((_path, params) => `workflows:read:${params.id}`), async (c) => {
+		const id = c.req.param("id");
+		const workflow = deps.workflows.get(id);
+		if (workflow === void 0) {
+			const err = new WorkflowNotFoundError(id);
+			return c.json({
+				error: err.kind,
+				message: err.message
+			}, 404);
+		}
+		const threadId = c.req.query("threadId");
+		if (threadId === void 0 || threadId.length === 0) return c.json({
+			error: "config-invalid",
+			message: "Query parameter `threadId` is required."
+		}, 400);
+		if (workflow.getState === void 0) return c.json({
+			error: "workflow-state-unsupported",
+			message: "Workflow does not implement getState()."
+		}, 400);
+		const state = await workflow.getState(threadId);
+		return c.json({
+			workflowId: id,
+			threadId,
+			state
+		});
+	});
+	app.get("/:id/checkpoints", createScopeMiddleware((_path, params) => `workflows:read:${params.id}`), async (c) => {
+		const id = c.req.param("id");
+		const workflow = deps.workflows.get(id);
+		if (workflow === void 0) {
+			const err = new WorkflowNotFoundError(id);
+			return c.json({
+				error: err.kind,
+				message: err.message
+			}, 404);
+		}
+		const threadId = c.req.query("threadId");
+		if (threadId === void 0 || threadId.length === 0) return c.json({
+			error: "config-invalid",
+			message: "Query parameter `threadId` is required."
+		}, 400);
+		if (workflow.listCheckpoints === void 0) return c.json({
+			error: "workflow-checkpoints-unsupported",
+			message: "Workflow does not implement listCheckpoints()."
+		}, 400);
+		const checkpoints = await workflow.listCheckpoints(threadId);
+		return c.json({
+			workflowId: id,
+			threadId,
+			checkpoints
+		});
+	});
+	app.post("/:id/fork", createScopeMiddleware((_path, params) => `workflows:execute:${params.id}`), async (c) => {
+		const id = c.req.param("id");
+		if (deps.workflows.get(id) === void 0) {
+			const err = new WorkflowNotFoundError(id);
+			return c.json({
+				error: err.kind,
+				message: err.message
+			}, 404);
+		}
+		const parsed = ForkBodySchema.safeParse(await safelyParseJson(c));
+		if (!parsed.success) return c.json({
+			error: "config-invalid",
+			message: "Invalid fork body.",
+			issues: parsed.error.issues.map((i) => ({
+				path: i.path,
+				message: i.message
+			}))
+		}, 400);
+		return c.json({
+			workflowId: id,
+			status: "pending",
+			fork: parsed.data
+		}, 202);
+	});
+	return app;
+}
+function backgroundExecute(workflow, body, tracker, runs, runId, streaming) {
+	const opts = { signal: tracker.signal };
+	if (body.threadId !== void 0) opts.threadId = body.threadId;
+	(async () => {
+		try {
+			for await (const ev of workflow.execute(body.input ?? {}, opts)) {
+				if (tracker.signal.aborted) break;
+				const type = typeof ev.type === "string" ? ev.type : "workflow.event";
+				streaming.dispatcher?.emit(streaming.subject, {
+					type,
+					payload: ev
+				});
+			}
+			runs.complete(runId, tracker.signal.aborted ? "aborted" : "completed");
+		} catch (err) {
+			streaming.dispatcher?.emit(streaming.subject, {
+				type: "workflow.error",
+				payload: {
+					runId,
+					message: err instanceof Error ? err.message : String(err)
+				}
+			});
+			runs.complete(runId, tracker.signal.aborted ? "aborted" : "failed", err);
+		}
+	})();
+}
+async function safelyParseJson(c) {
+	try {
+		return await c.req.json();
+	} catch {
+		return {};
+	}
+}
+
+//#endregion
+export { createWorkflowRoutes };
+//# sourceMappingURL=workflows.js.map

package/dist/routes/workflows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.js","names":["opts: { signal?: AbortSignal; threadId?: string }"],"sources":["../../src/routes/workflows.ts"],"sourcesContent":["/**\n * Workflow REST routes.\n *\n *   POST   /workflows/:id/execute              (idempotent; scope `workflows:execute`)\n *   POST   /workflows/:id/resume               (scope `workflows:resume[:id]`)\n *   GET    /workflows/:id/state                (scope `workflows:read`)\n *   GET    /workflows/:id/checkpoints          (scope `workflows:read`)\n *   POST   /workflows/:id/fork                 (scope `workflows:execute`)\n *\n * @packageDocumentation\n */\n\nimport type { Context } from 'hono';\nimport { Hono } from 'hono';\nimport { z } from 'zod';\n\nimport { WorkflowNotFoundError } from '../errors/index.js';\nimport type { ServerVariables } from '../internal/context.js';\nimport { newRequestId } from '../internal/ids.js';\nimport { createScopeMiddleware } from '../middleware/scope.js';\nimport type { WorkflowRegistry } from '../registry/index.js';\nimport type { RunStateTracker } from '../runtime/run-state.js';\n\n/**\n * @stable\n */\nexport interface WorkflowRoutesDeps {\n  readonly workflows: WorkflowRegistry;\n  readonly runs: RunStateTracker;\n  readonly newRunId?: () => string;\n  /** Streaming dispatcher (IP-2): workflow events reach the run subject. */\n  readonly dispatcher?: import('../ws/dispatcher.js').WsDispatcher;\n}\n\nconst ExecuteBodySchema = z\n  .object({\n    input: z.unknown().optional(),\n    threadId: z.string().min(1).optional(),\n    sessionId: z.string().min(1).optional(),\n    userId: z.string().min(1).optional(),\n  })\n  .strict()\n  .default({});\n\nconst ResumeBodySchema = z\n  .object({\n    threadId: z.string().min(1),\n    resume: z.unknown().optional(),\n  })\n  .strict();\n\nconst ForkBodySchema = z\n  .object({\n    fromThreadId: z.string().min(1),\n    fromCheckpointId: z.string().min(1).optional(),\n  })\n  .strict();\n\n/**\n * @stable\n */\nexport function createWorkflowRoutes(\n  deps: WorkflowRoutesDeps,\n): Hono<{ Variables: ServerVariables }> {\n  const app = new Hono<{ Variables: ServerVariables }>();\n  const newRunId = deps.newRunId ?? newRequestId;\n\n  app.get('/', createScopeMiddleware('workflows:read'), (c) =>\n    c.json({ workflows: deps.workflows.list() }),\n  );\n\n  app.post(\n    '/:id/execute',\n    createScopeMiddleware((_path, params) => `workflows:execute:${params.id}`),\n    async (c) => {\n      const id = c.req.param('id');\n      const workflow = deps.workflows.get(id);\n      if (workflow === undefined) {\n        const err = new WorkflowNotFoundError(id);\n        return c.json({ error: err.kind, message: err.message }, 404);\n      }\n      const parsed = ExecuteBodySchema.safeParse(await safelyParseJson(c));\n      if (!parsed.success) {\n        return c.json(\n          {\n            error: 'config-invalid',\n            message: 'Invalid execute body.',\n            issues: parsed.error.issues.map((i) => ({ path: i.path, message: i.message })),\n          },\n          400,\n        );\n      }\n      const runId = newRunId();\n      const tracker = deps.runs.start(runId, {\n        kind: 'workflow',\n        workflowId: id,\n        ...(parsed.data.threadId !== undefined ? { threadId: parsed.data.threadId } : {}),\n        ...(parsed.data.sessionId !== undefined ? { sessionId: parsed.data.sessionId } : {}),\n        ...(parsed.data.userId !== undefined ? { userId: parsed.data.userId } : {}),\n      });\n      // Workflows are streaming-first; the REST endpoint kicks off the\n      // run in the background and returns 202 + runId. The actual\n      // event stream is consumed via WebSocket / SSE in Phase 14b.\n      const subject = `workflow:${id}/runs/${runId}/events`;\n      backgroundExecute(workflow, parsed.data, tracker, deps.runs, runId, {\n        subject,\n        ...(deps.dispatcher !== undefined ? { dispatcher: deps.dispatcher } : {}),\n      });\n      return c.json(\n        {\n          runId,\n          status: 'running',\n          subscribe: {\n            // IP-2: the previously-advertised SSE URL was never\n            // mounted; the WS subject (now in the grammar) delivers.\n            websocket: subject,\n          },\n        },\n        202,\n      );\n    },\n  );\n\n  app.post(\n    '/:id/resume',\n    createScopeMiddleware((_path, params) => `workflows:resume:${params.id}`),\n    async (c) => {\n      const id = c.req.param('id');\n      const workflow = deps.workflows.get(id);\n      if (workflow === undefined) {\n        const err = new WorkflowNotFoundError(id);\n        return c.json({ error: err.kind, message: err.message }, 404);\n      }\n      const parsed = ResumeBodySchema.safeParse(await safelyParseJson(c));\n      if (!parsed.success) {\n        return c.json(\n          {\n            error: 'config-invalid',\n            message: 'Invalid resume body.',\n            issues: parsed.error.issues.map((i) => ({ path: i.path, message: i.message })),\n          },\n          400,\n        );\n      }\n      if (workflow.resume === undefined) {\n        return c.json(\n          {\n            error: 'workflow-resume-unsupported',\n            message: `Workflow '${id}' does not implement resume().`,\n          },\n          400,\n        );\n      }\n      const runId = newRunId();\n      deps.runs.declare(runId, {\n        kind: 'workflow',\n        workflowId: id,\n        threadId: parsed.data.threadId,\n      });\n      return c.json(\n        {\n          runId,\n          threadId: parsed.data.threadId,\n          status: 'pending',\n          subscribe: {\n            websocket: `workflow:${id}/runs/${runId}/events`,\n            sse: `/v1/runs/${runId}/events`,\n          },\n        },\n        202,\n      );\n    },\n  );\n\n  app.get(\n    '/:id/state',\n    createScopeMiddleware((_path, params) => `workflows:read:${params.id}`),\n    async (c) => {\n      const id = c.req.param('id');\n      const workflow = deps.workflows.get(id);\n      if (workflow === undefined) {\n        const err = new WorkflowNotFoundError(id);\n        return c.json({ error: err.kind, message: err.message }, 404);\n      }\n      const threadId = c.req.query('threadId');\n      if (threadId === undefined || threadId.length === 0) {\n        return c.json(\n          { error: 'config-invalid', message: 'Query parameter `threadId` is required.' },\n          400,\n        );\n      }\n      if (workflow.getState === undefined) {\n        return c.json(\n          {\n            error: 'workflow-state-unsupported',\n            message: 'Workflow does not implement getState().',\n          },\n          400,\n        );\n      }\n      const state = await workflow.getState(threadId);\n      return c.json({ workflowId: id, threadId, state });\n    },\n  );\n\n  app.get(\n    '/:id/checkpoints',\n    createScopeMiddleware((_path, params) => `workflows:read:${params.id}`),\n    async (c) => {\n      const id = c.req.param('id');\n      const workflow = deps.workflows.get(id);\n      if (workflow === undefined) {\n        const err = new WorkflowNotFoundError(id);\n        return c.json({ error: err.kind, message: err.message }, 404);\n      }\n      const threadId = c.req.query('threadId');\n      if (threadId === undefined || threadId.length === 0) {\n        return c.json(\n          { error: 'config-invalid', message: 'Query parameter `threadId` is required.' },\n          400,\n        );\n      }\n      if (workflow.listCheckpoints === undefined) {\n        return c.json(\n          {\n            error: 'workflow-checkpoints-unsupported',\n            message: 'Workflow does not implement listCheckpoints().',\n          },\n          400,\n        );\n      }\n      const checkpoints = await workflow.listCheckpoints(threadId);\n      return c.json({ workflowId: id, threadId, checkpoints });\n    },\n  );\n\n  app.post(\n    '/:id/fork',\n    createScopeMiddleware((_path, params) => `workflows:execute:${params.id}`),\n    async (c) => {\n      const id = c.req.param('id');\n      const workflow = deps.workflows.get(id);\n      if (workflow === undefined) {\n        const err = new WorkflowNotFoundError(id);\n        return c.json({ error: err.kind, message: err.message }, 404);\n      }\n      const parsed = ForkBodySchema.safeParse(await safelyParseJson(c));\n      if (!parsed.success) {\n        return c.json(\n          {\n            error: 'config-invalid',\n            message: 'Invalid fork body.',\n            issues: parsed.error.issues.map((i) => ({ path: i.path, message: i.message })),\n          },\n          400,\n        );\n      }\n      // Fork delegates to the workflow's own primitives in Phase 14b/c.\n      // Phase 14a returns a structured 202 with the fork descriptor so\n      // the API contract is reachable today.\n      return c.json(\n        {\n          workflowId: id,\n          status: 'pending',\n          fork: parsed.data,\n        },\n        202,\n      );\n    },\n  );\n\n  return app;\n}\n\nfunction backgroundExecute(\n  workflow: NonNullable<ReturnType<WorkflowRegistry['get']>>,\n  body: z.infer<typeof ExecuteBodySchema>,\n  tracker: { readonly signal: AbortSignal },\n  runs: RunStateTracker,\n  runId: string,\n  streaming: {\n    readonly subject: string;\n    readonly dispatcher?: import('../ws/dispatcher.js').WsDispatcher;\n  },\n): void {\n  const opts: { signal?: AbortSignal; threadId?: string } = { signal: tracker.signal };\n  if (body.threadId !== undefined) opts.threadId = body.threadId;\n  void (async () => {\n    try {\n      // IP-2: every workflow event reaches the dispatcher — the old\n      // loop iterated the stream and threw each event away.\n      for await (const ev of workflow.execute(body.input ?? {}, opts)) {\n        if (tracker.signal.aborted) break;\n        const type =\n          typeof (ev as { type?: unknown }).type === 'string'\n            ? (ev as { type: string }).type\n            : 'workflow.event';\n        streaming.dispatcher?.emit(streaming.subject, { type, payload: ev });\n      }\n      runs.complete(runId, tracker.signal.aborted ? 'aborted' : 'completed');\n    } catch (err) {\n      streaming.dispatcher?.emit(streaming.subject, {\n        type: 'workflow.error',\n        payload: { runId, message: err instanceof Error ? err.message : String(err) },\n      });\n      runs.complete(runId, tracker.signal.aborted ? 'aborted' : 'failed', err);\n    }\n  })();\n}\n\nasync function safelyParseJson(c: Context<{ Variables: ServerVariables }>): Promise<unknown> {\n  try {\n    return await c.req.json();\n  } catch {\n    return {};\n  }\n}\n"],"mappings":"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"}

package/dist/runtime/run-state.d.ts

@@ -0,0 +1,158 @@
+//#region src/runtime/run-state.d.ts
+/**
+ * In-memory bookkeeping for in-flight agent / workflow runs. Exposes
+ * a tiny CRUD surface route handlers consume to honour the
+ * `GET /runs/:runId/state` and `POST /runs/:runId/abort` endpoints
+ * declared in the runtime architecture.
+ *
+ * The full durable resume / replay path lives in Phase 14b/c on top
+ * of the WebSocket layer + the consolidator daemon. Phase 14a only
+ * needs enough state to:
+ *   - mint a runId on every `POST /run` / `POST /stream`,
+ *   - track its lifecycle (`pending` → `running` → `completed` / `failed` / `aborted`),
+ *   - propagate `AbortController.signal` so handlers can cancel.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Stable status discriminator for a run snapshot. Mirrors the values
+ * exposed on the public REST surface.
+ *
+ * @stable
+ */
+type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'aborted';
+/**
+ * Identifying tag for the underlying execution kind. Workflows run
+ * on the durable engine in `@graphorin/workflow`; agents run on the
+ * `@graphorin/agent` runtime.
+ *
+ * @stable
+ */
+type RunKind = 'agent' | 'workflow';
+/**
+ * Terminal status a run can settle into (never `pending` / `running`).
+ *
+ * @stable
+ */
+type TerminalRunStatus = Extract<RunStatus, 'completed' | 'failed' | 'aborted'>;
+/**
+ * IP-15: payload handed to the {@link RunStateTracker} `onTerminal` callback
+ * the first time a run reaches a terminal state. The server turns this into
+ * the `graphorin_agent_runs_total` counter + `graphorin_agent_run_duration_seconds`
+ * summary. `durationMs` is omitted for a run that was aborted before it ever
+ * started (no meaningful wall-clock).
+ *
+ * @stable
+ */
+interface TerminalRunInfo {
+  readonly status: TerminalRunStatus;
+  readonly kind: RunKind;
+  readonly durationMs?: number;
+}
+/**
+ * Snapshot returned by {@link RunStateTracker.snapshot}.
+ *
+ * @stable
+ */
+interface RunStateSnapshot {
+  readonly runId: string;
+  readonly kind: RunKind;
+  readonly status: RunStatus;
+  readonly startedAt?: number;
+  readonly completedAt?: number;
+  readonly error?: {
+    readonly message: string;
+  };
+  readonly agentId?: string;
+  readonly workflowId?: string;
+  readonly threadId?: string;
+  readonly sessionId?: string;
+  readonly userId?: string;
+}
+/**
+ * Bookkeeping descriptor recorded at run start. Either an agent run
+ * (with `agentId`) or a workflow run (with `workflowId` + optional
+ * `threadId`).
+ *
+ * @stable
+ */
+type RunDescriptor = {
+  readonly kind: 'agent';
+  readonly agentId: string;
+  readonly sessionId?: string;
+  readonly userId?: string;
+} | {
+  readonly kind: 'workflow';
+  readonly workflowId: string;
+  readonly threadId?: string;
+  readonly sessionId?: string;
+  readonly userId?: string;
+};
+/**
+ * In-flight handle returned by {@link RunStateTracker.start}. Handlers
+ * pass `signal` into the underlying `agent.run / workflow.execute`
+ * invocation so cancellation propagates instantly.
+ *
+ * @stable
+ */
+interface RunHandle {
+  readonly runId: string;
+  readonly signal: AbortSignal;
+  cancel(reason?: unknown): void;
+}
+/**
+ * Pluggable tracker. The default in-memory implementation is the only
+ * one shipped in Phase 14a; future phases plug in a SQLite-backed
+ * variant so durable resume survives process restarts.
+ *
+ * @stable
+ */
+declare class RunStateTracker {
+  #private;
+  constructor(options?: {
+    readonly now?: () => number;
+    /**
+     * IP-15: invoked exactly once per run, the first time it settles into a
+     * terminal state. Used to drive the run-count + duration metrics. Never
+     * throws into the tracker — wrap your handler if it might.
+     */
+    readonly onTerminal?: (info: TerminalRunInfo) => void;
+  });
+  /** Reserve a run id without taking ownership of an AbortSignal. */
+  declare(runId: string, descriptor: RunDescriptor): void;
+  /** Promote a previously-declared run to `running` (or declare it). */
+  start(runId: string, descriptor: RunDescriptor): RunHandle;
+  /** Mark a run as terminal. */
+  complete(runId: string, status: Extract<RunStatus, 'completed' | 'failed' | 'aborted'>, err?: unknown): void;
+  /** Cancel a run via its `AbortController`. */
+  abort(runId: string, reason?: unknown): boolean;
+  /** Read-only snapshot, safe to JSON.stringify. */
+  snapshot(runId: string): RunStateSnapshot | undefined;
+  /**
+   * Number of runs currently in `pending` or `running`. Useful for
+   * snapshots / metrics. Note that `pending` runs hold a reservation
+   * but have not yet started any work — see {@link runningCount} for
+   * the drain-blocking subset.
+   */
+  inflightCount(): number;
+  /**
+   * Number of runs with active work in progress (`running`). The
+   * lifecycle drain blocks on this counter only — pending runs are a
+   * pure reservation (e.g. an awaited WS subscription) and can be
+   * aborted immediately when SIGTERM arrives.
+   */
+  runningCount(): number;
+  /**
+   * Drop every reserved-but-not-yet-started run. Called by the
+   * server lifecycle at the start of `stop()` so the drain only
+   * waits for actual work in flight.
+   */
+  abortPending(reason?: unknown): number;
+  /** Drop terminal records older than `olderThan`. */
+  prune(olderThan: number): number;
+  /** Cancel every in-flight run. Used during graceful shutdown. */
+  abortAll(reason?: unknown): number;
+}
+//#endregion
+export { RunDescriptor, RunHandle, RunStateSnapshot, RunStateTracker, RunStatus };
+//# sourceMappingURL=run-state.d.ts.map

package/dist/runtime/run-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-state.d.ts","names":[],"sources":["../../src/runtime/run-state.ts"],"sourcesContent":[],"mappings":";;AAsBA;AASA;AAOA;AAWA;AAeA;AAqBA;AAsBA;AAwBA;;;;;;;;;;;;;KA7GY,SAAA;;;;;;;;KASA,OAAA;;;;;;KAOA,iBAAA,GAAoB,QAAQ;;;;;;;;;;UAWvB,eAAA;mBACE;iBACF;;;;;;;;UAaA,gBAAA;;iBAEA;mBACE;;;;;;;;;;;;;;;;;;;KAkBP,aAAA;;;;;;;;;;;;;;;;;;;UAsBK,SAAA;;mBAEE;;;;;;;;;;cAsBN,eAAA;;;;;;;;;iCAasB;;;qCAsBE;;mCAaF,gBAAgB;;kCA0BvC,QAAQ;;;;2BAgCO"}