@treeseed/core 0.4.2 → 0.4.4

package/README.md

@@ -1,6 +1,6 @@
 # @treeseed/core
 
-`@treeseed/core` is the Treeseed Research Hub package for Astro/Starlight sites. It contains the published site runtime, shared components and styles, the knowledge-factory content model, and the Astro-specific forms stack used by Treeseed tenants.
+`@treeseed/core` is the Treeseed integrated platform starter for Astro/Starlight sites and Hono API runtimes. It contains the published web runtime, API runtime, integrated local dev orchestration, shared components and styles, the knowledge-factory content model, and the forms stack used by Treeseed tenants.
 
 This repository is the package root. Run package commands from [`core`](./), not from the top-level `treeseed` workspace.
 
@@ -54,6 +54,9 @@ This keeps the shared fixture canonical while preserving Core’s package bounda
 ### Core development
 
 ```bash
+npm run dev
+npm run dev:web
+npm run dev:api
 npm run fixtures:check
 npm run build:dist
 npm run test:unit
@@ -64,6 +67,9 @@ npm run test:smoke
 
 What they do:
 
+- `dev`: starts the integrated Astro UI and Hono API local runtime from `core`
+- `dev:web`: starts only the Astro UI dev surface through the `core` runtime
+- `dev:api`: starts only the Hono API dev surface through the `core` runtime
 - `fixtures:check`: verifies that the pinned shared fixture is initialized and usable
 - `build:dist`: builds the publishable `dist/` package output
 - `test:unit`: runs package unit tests with Vitest

package/dist/api/agent-routes.d.ts

@@ -0,0 +1,13 @@
+import type { Hono } from 'hono';
+import type { AgentSdk } from '@treeseed/sdk';
+import type { GatewayQueueProducer } from './types.ts';
+interface RegisterAgentRoutesOptions {
+    sdk: AgentSdk;
+    prefix?: string;
+    scope?: string | null;
+    projectId?: string;
+    queueProducer?: GatewayQueueProducer;
+    defaultActor?: string;
+}
+export declare function registerAgentRoutes(app: Hono<any>, options: RegisterAgentRoutesOptions): void;
+export {};

package/dist/api/agent-routes.js

@@ -0,0 +1,402 @@
+import crypto from "node:crypto";
+import { jsonError, requireScope } from "./http.js";
+async function importOptionalAgentRuntime() {
+  try {
+    const dynamicImport = new Function("specifier", "return import(specifier)");
+    return await dynamicImport("@treeseed/agent");
+  } catch {
+    return null;
+  }
+}
+async function listRegisteredHandlers() {
+  const agent = await importOptionalAgentRuntime();
+  return agent?.listRegisteredAgentHandlers?.() ?? [];
+}
+function queueEnvelopeForTask(task) {
+  return {
+    messageId: crypto.randomUUID(),
+    taskId: String(task.id ?? ""),
+    workDayId: String(task.workDayId ?? task.work_day_id ?? ""),
+    agentId: String(task.agentId ?? task.agent_id ?? ""),
+    taskType: String(task.type ?? ""),
+    idempotencyKey: String(task.idempotencyKey ?? task.idempotency_key ?? ""),
+    attempt: Number(task.attemptCount ?? task.attempt_count ?? 0) + 1,
+    payloadRef: `d1:tasks/${String(task.id ?? "")}`,
+    graphVersion: task.graphVersion !== void 0 && task.graphVersion !== null ? String(task.graphVersion) : task.graph_version !== void 0 && task.graph_version !== null ? String(task.graph_version) : null,
+    budgetHint: 1
+  };
+}
+function withPrefix(prefix, path) {
+  return `${prefix}${path}`.replace(/\/{2,}/g, "/");
+}
+function actor(body, fallback) {
+  return String(body.actor ?? fallback);
+}
+async function enqueueTask(options, request) {
+  if (!options.queueProducer) {
+    throw new Error("Queue producer not configured.");
+  }
+  const task = await options.sdk.get({ model: "task", id: request.taskId });
+  if (!task.payload) {
+    throw new Error("Unknown task.");
+  }
+  await options.queueProducer.enqueue({
+    queueName: request.queueName,
+    message: queueEnvelopeForTask(task.payload),
+    delaySeconds: request.deliveryDelaySeconds ?? 0
+  });
+  await options.sdk.recordTaskProgress({
+    id: request.taskId,
+    state: "queued",
+    appendEvent: { kind: "queued", data: { queueName: request.queueName ?? null } },
+    actor: request.actor
+  });
+  return { ok: true, taskId: request.taskId, queued: true };
+}
+async function buildTaskContext(sdk, taskId) {
+  const context = await sdk.getManagerContext(taskId);
+  const task = context.payload.task;
+  const agent = task ? (await sdk.get({ model: "agent", slug: String(task.agentId) })).payload : null;
+  return {
+    ...context.payload,
+    agent
+  };
+}
+function registerAgentRoutes(app, options) {
+  const prefix = options.prefix ?? "/agent";
+  const defaultActor = options.defaultActor ?? "api";
+  app.get(withPrefix(prefix, "/healthz"), async (c) => c.json({
+    ok: true,
+    service: "treeseed-agent-api",
+    handlerCount: (await listRegisteredHandlers()).length
+  }));
+  app.get(withPrefix(prefix, "/specs"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const payload = await options.sdk.listAgentSpecs({ enabled: true });
+    return c.json({
+      ok: true,
+      payload,
+      handlers: await listRegisteredHandlers()
+    });
+  });
+  app.post(withPrefix(prefix, "/workdays/start"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const body = await c.req.json().catch(() => ({}));
+    const graphRefresh = await options.sdk.refreshGraph();
+    const result = await options.sdk.startWorkDay({
+      id: typeof body.id === "string" ? body.id : void 0,
+      projectId: String(body.projectId ?? options.projectId ?? "treeseed-market"),
+      capacityBudget: body.capacityBudget === void 0 ? void 0 : Number(body.capacityBudget),
+      graphVersion: typeof body.graphVersion === "string" ? body.graphVersion : graphRefresh.snapshotRoot,
+      summary: body.summary ?? { graphRefresh },
+      actor: actor(body, defaultActor)
+    });
+    return c.json(result);
+  });
+  app.post(withPrefix(prefix, "/workdays/:id/close"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const body = await c.req.json().catch(() => ({}));
+    const result = await options.sdk.closeWorkDay({
+      id: c.req.param("id"),
+      state: body.state,
+      summary: body.summary ?? null,
+      actor: actor(body, defaultActor)
+    });
+    return result.payload ? c.json(result) : jsonError(c, 404, "Unknown work day.");
+  });
+  app.post(withPrefix(prefix, "/tasks"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const body = await c.req.json().catch(() => ({}));
+    const result = await options.sdk.createTask({
+      id: typeof body.id === "string" ? body.id : void 0,
+      workDayId: String(body.workDayId ?? ""),
+      agentId: String(body.agentId ?? ""),
+      type: String(body.type ?? ""),
+      state: typeof body.state === "string" ? body.state : "pending",
+      priority: body.priority === void 0 ? void 0 : Number(body.priority),
+      idempotencyKey: String(body.idempotencyKey ?? ""),
+      payload: body.payload ?? {},
+      payloadHash: typeof body.payloadHash === "string" ? body.payloadHash : null,
+      maxAttempts: body.maxAttempts === void 0 ? void 0 : Number(body.maxAttempts),
+      availableAt: typeof body.availableAt === "string" ? body.availableAt : void 0,
+      graphVersion: typeof body.graphVersion === "string" ? body.graphVersion : null,
+      parentTaskId: typeof body.parentTaskId === "string" ? body.parentTaskId : null,
+      actor: actor(body, defaultActor)
+    });
+    return c.json(result);
+  });
+  app.post(withPrefix(prefix, "/tasks/search"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const body = await c.req.json().catch(() => ({}));
+    const result = await options.sdk.searchTasks({
+      workDayId: typeof body.workDayId === "string" ? body.workDayId : void 0,
+      agentId: typeof body.agentId === "string" ? body.agentId : void 0,
+      state: Array.isArray(body.state) || typeof body.state === "string" ? body.state : void 0,
+      limit: body.limit === void 0 ? void 0 : Number(body.limit)
+    });
+    return c.json(result);
+  });
+  app.post(withPrefix(prefix, "/tasks/:id/claim"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const body = await c.req.json().catch(() => ({}));
+    const result = await options.sdk.claimTask({
+      id: c.req.param("id"),
+      workerId: String(body.workerId ?? "worker"),
+      leaseSeconds: Number(body.leaseSeconds ?? 120),
+      actor: actor(body, defaultActor)
+    });
+    return result.payload ? c.json(result) : jsonError(c, 404, "Unknown task.");
+  });
+  app.post(withPrefix(prefix, "/tasks/:id/progress"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const body = await c.req.json().catch(() => ({}));
+    const result = await options.sdk.recordTaskProgress({
+      id: c.req.param("id"),
+      workerId: typeof body.workerId === "string" ? body.workerId : null,
+      state: typeof body.state === "string" ? body.state : void 0,
+      appendEvent: body.appendEvent,
+      patch: body.patch,
+      actor: actor(body, defaultActor)
+    });
+    return result.payload ? c.json(result) : jsonError(c, 404, "Unknown task.");
+  });
+  app.post(withPrefix(prefix, "/tasks/:id/complete"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const body = await c.req.json().catch(() => ({}));
+    const result = await options.sdk.completeTask({
+      id: c.req.param("id"),
+      output: body.output ?? null,
+      outputRef: typeof body.outputRef === "string" ? body.outputRef : null,
+      summary: body.summary ?? null,
+      actor: actor(body, defaultActor)
+    });
+    return result.payload ? c.json(result) : jsonError(c, 404, "Unknown task.");
+  });
+  app.post(withPrefix(prefix, "/tasks/:id/fail"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const body = await c.req.json().catch(() => ({}));
+    const result = await options.sdk.failTask({
+      id: c.req.param("id"),
+      errorCode: typeof body.errorCode === "string" ? body.errorCode : null,
+      errorMessage: String(body.errorMessage ?? "Task failed"),
+      retryable: Boolean(body.retryable),
+      nextVisibleAt: typeof body.nextVisibleAt === "string" ? body.nextVisibleAt : null,
+      actor: actor(body, defaultActor)
+    });
+    return result.payload ? c.json(result) : jsonError(c, 404, "Unknown task.");
+  });
+  app.post(withPrefix(prefix, "/tasks/:id/requeue"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const body = await c.req.json().catch(() => ({}));
+    try {
+      return c.json(await enqueueTask(options, {
+        taskId: c.req.param("id"),
+        queueName: typeof body.queueName === "string" ? body.queueName : void 0,
+        deliveryDelaySeconds: body.delaySeconds === void 0 ? void 0 : Number(body.delaySeconds),
+        actor: actor(body, defaultActor)
+      }));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return jsonError(c, /Unknown task/.test(message) ? 404 : /Queue producer/.test(message) ? 501 : 500, message);
+    }
+  });
+  app.post(withPrefix(prefix, "/tasks/:id/followups"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const body = await c.req.json().catch(() => ({}));
+    const current = await options.sdk.get({ model: "task", id: c.req.param("id") });
+    if (!current.payload) {
+      return jsonError(c, 404, "Unknown task.");
+    }
+    const currentTask = current.payload;
+    const followups = Array.isArray(body.followups) ? body.followups : [];
+    const created = [];
+    for (const followup of followups) {
+      created.push(await options.sdk.createTask({
+        workDayId: String(followup.workDayId ?? currentTask.workDayId ?? ""),
+        agentId: String(followup.agentId ?? currentTask.agentId ?? ""),
+        type: String(followup.type ?? "followup"),
+        priority: followup.priority === void 0 ? void 0 : Number(followup.priority),
+        idempotencyKey: String(followup.idempotencyKey ?? `${c.req.param("id")}:${created.length}`),
+        payload: followup.payload ?? {},
+        graphVersion: typeof followup.graphVersion === "string" ? followup.graphVersion : null,
+        parentTaskId: c.req.param("id"),
+        actor: actor(followup, defaultActor)
+      }));
+    }
+    return c.json({ ok: true, payload: created.map((entry) => entry.payload) });
+  });
+  app.post(withPrefix(prefix, "/queue/enqueue"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const body = await c.req.json().catch(() => ({}));
+    try {
+      return c.json(await enqueueTask(options, {
+        taskId: String(body.taskId ?? ""),
+        queueName: typeof body.queueName === "string" ? body.queueName : void 0,
+        deliveryDelaySeconds: body.deliveryDelaySeconds === void 0 ? void 0 : Number(body.deliveryDelaySeconds),
+        actor: actor(body, defaultActor)
+      }));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return jsonError(c, /Unknown task/.test(message) ? 404 : /Queue producer/.test(message) ? 501 : 500, message);
+    }
+  });
+  app.post(withPrefix(prefix, "/reports"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const body = await c.req.json().catch(() => ({}));
+    const result = await options.sdk.createReport({
+      id: typeof body.id === "string" ? body.id : void 0,
+      workDayId: String(body.workDayId ?? ""),
+      kind: String(body.kind ?? "workday_summary"),
+      body: body.body ?? {},
+      renderedRef: typeof body.renderedRef === "string" ? body.renderedRef : null,
+      sentAt: typeof body.sentAt === "string" ? body.sentAt : null,
+      actor: actor(body, defaultActor)
+    });
+    return c.json(result);
+  });
+  app.post(withPrefix(prefix, "/context/resolve-task"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const body = await c.req.json().catch(() => ({}));
+    return c.json({
+      ok: true,
+      payload: await buildTaskContext(options.sdk, String(body.taskId ?? ""))
+    });
+  });
+  app.post(withPrefix(prefix, "/graph/search"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const body = await c.req.json().catch(() => ({}));
+    const query = String(body.query ?? "");
+    const scope = String(body.scope ?? "sections");
+    const payload = scope === "files" ? await options.sdk.searchFiles(query, body.options) : scope === "entities" ? await options.sdk.searchEntities(query, body.options) : await options.sdk.searchSections(query, body.options);
+    return c.json({ ok: true, payload });
+  });
+  app.post(withPrefix(prefix, "/graph/subgraph"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const body = await c.req.json().catch(() => ({}));
+    const payload = await options.sdk.getSubgraph(
+      Array.isArray(body.seedIds) ? body.seedIds.map(String) : [],
+      body.options
+    );
+    return c.json({ ok: true, payload });
+  });
+  app.post(withPrefix(prefix, "/graph/query"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const body = await c.req.json().catch(() => ({}));
+    const payload = await options.sdk.queryGraph(body);
+    if (typeof body.workDayId === "string" && body.workDayId) {
+      await options.sdk.create({
+        model: "graph_run",
+        data: {
+          workDayId: body.workDayId,
+          corpusHash: String(body.corpusHash ?? "query-graph"),
+          graphVersion: String(body.graphVersion ?? ""),
+          queryJson: JSON.stringify(body),
+          seedIdsJson: JSON.stringify(payload.seedIds),
+          selectedNodeIdsJson: JSON.stringify(payload.nodes.map((entry) => entry.node.id)),
+          statsJson: JSON.stringify({ nodeCount: payload.nodes.length, edgeCount: payload.edges.length })
+        },
+        actor: actor(body, defaultActor)
+      });
+    }
+    return c.json({ ok: true, payload });
+  });
+  app.post(withPrefix(prefix, "/graph/context-pack"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const body = await c.req.json().catch(() => ({}));
+    const payload = await options.sdk.buildContextPack(body);
+    if (typeof body.workDayId === "string" && body.workDayId) {
+      await options.sdk.create({
+        model: "graph_run",
+        data: {
+          workDayId: body.workDayId,
+          corpusHash: String(body.corpusHash ?? "context-pack"),
+          graphVersion: String(body.graphVersion ?? ""),
+          queryJson: JSON.stringify(body),
+          seedIdsJson: JSON.stringify(payload.seedIds),
+          selectedNodeIdsJson: JSON.stringify(payload.includedNodeIds),
+          statsJson: JSON.stringify({
+            nodeCount: payload.nodes.length,
+            edgeCount: payload.edges.length,
+            totalTokenEstimate: payload.totalTokenEstimate
+          })
+        },
+        actor: actor(body, defaultActor)
+      });
+    }
+    return c.json({ ok: true, payload });
+  });
+  app.post(withPrefix(prefix, "/graph/parse-dsl"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const body = await c.req.json().catch(() => ({}));
+    const payload = await options.sdk.parseGraphDsl(String(body.source ?? body.query ?? ""));
+    return c.json({ ok: true, payload });
+  });
+  app.get(withPrefix(prefix, "/graph/node/:id"), async (c) => {
+    if (options.scope) {
+      const unauthorized = requireScope(c, options.scope);
+      if (unauthorized) return unauthorized;
+    }
+    const payload = await options.sdk.getGraphNode(c.req.param("id"));
+    return payload ? c.json({ ok: true, payload }) : jsonError(c, 404, "Unknown graph node.");
+  });
+}
+export {
+  registerAgentRoutes
+};

package/dist/api/app.d.ts

@@ -0,0 +1,5 @@
+import { Hono } from 'hono';
+import type { ApiServerOptions, AppVariables } from './types.ts';
+export declare function createTreeseedApiApp(options?: ApiServerOptions): Hono<{
+    Variables: AppVariables;
+}, import("hono/types").BlankSchema, "/">;