@stigmer/mcp-server 3.2.2 → 3.3.0

package/src/domains/records/records.integration.test.ts

@@ -0,0 +1,313 @@
+// In-process integration test for the record tools (search-pattern:
+// real Connect backend with stubbed record services, real MCP client
+// over an in-memory transport).
+//
+// Verifies the T05 contract surface:
+//   - the records-only roster is exactly the five tools (T05 R1), with
+//     honest annotations surfaced through tools/list (pinning the SDK's
+//     annotations support) and NO org argument (agent audience);
+//   - the main roster carries the same five tools WITH the org argument
+//     (direct audience);
+//   - argument → request mapping (typed filter, "in" → is_in, paging);
+//   - the records-own error mapper: domain errors pass the server's
+//     message verbatim as {error, code, reason, constraint} JSON with
+//     ErrorInfo companions; transport errors delegate to the shared
+//     classifier (DD-005 SD-6).
+
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError, type ConnectRouter } from "@connectrpc/connect";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import {
+  createServer as createHttp2Server,
+  type Http2Server,
+  type ServerHttp2Session,
+} from "node:http2";
+import type { AddressInfo } from "node:net";
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { DatastoreRecordCommandController } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_command_pb";
+import {
+  DatastoreDescriptionSchema,
+  RecordEnvelopeSchema,
+  RecordListSchema,
+  type FindRecordsRequest,
+  type InsertRecordRequest,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_io_pb";
+import { DatastoreRecordQueryController } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_query_pb";
+import { ErrorInfoSchema } from "@stigmer/protos/google/rpc/error_details_pb";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { configureLogger } from "../../logger";
+import { createRecordsServer, createServer } from "../../server";
+
+configureLogger({ level: "error", format: "text" });
+
+const RECORD_TOOLS = [
+  "describe_datastore",
+  "find_records",
+  "insert_record",
+  "update_record",
+  "delete_record",
+];
+
+let backend: Http2Server;
+let client: Client;
+const openSessions = new Set<ServerHttp2Session>();
+
+/** The next stubbed outcome per RPC; tests set these. */
+let findResponse: () => ReturnType<typeof create<typeof RecordListSchema>>;
+let insertOutcome: () => ReturnType<typeof create<typeof RecordEnvelopeSchema>>;
+
+/**
+ * Requests the stubs captured. An object (not two `let`s) because TS
+ * does not reset let-narrowing across awaited calls for closure
+ * assignments — property narrowing it does.
+ */
+const captured: {
+  find?: FindRecordsRequest;
+  insert?: InsertRecordRequest;
+} = {};
+
+interface ToolResult {
+  content: Array<{ type: string; text?: string }>;
+  isError?: boolean;
+}
+
+async function callTool(name: string, args: Record<string, unknown>): Promise<ToolResult> {
+  return (await client.callTool({ name, arguments: args })) as ToolResult;
+}
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(DatastoreRecordQueryController, {
+      findRecords: (req) => {
+        captured.find = req;
+        return findResponse();
+      },
+      describeDatastore: () =>
+        create(DatastoreDescriptionSchema, {
+          datastore: "clinic",
+          timezone: "Asia/Kolkata",
+          partitions: ["default"],
+        }),
+    });
+    router.service(DatastoreRecordCommandController, {
+      insertRecord: (req) => {
+        captured.insert = req;
+        return insertOutcome();
+      },
+      updateRecord: () => create(RecordEnvelopeSchema, { id: "dsr_updated" }),
+      deleteRecord: () => create(RecordEnvelopeSchema, { id: "dsr_deleted" }),
+    });
+  };
+  backend = createHttp2Server(connectNodeAdapter({ routes }));
+  backend.on("session", (session) => {
+    openSessions.add(session);
+    session.on("close", () => openSessions.delete(session));
+  });
+  await new Promise<void>((resolve) => backend.listen(0, "127.0.0.1", resolve));
+  const port = (backend.address() as AddressInfo).port;
+
+  // The records-only roster is the surface under test — the audience
+  // the runner-synthesized attachment serves.
+  const mcp = createRecordsServer({ serverAddress: `127.0.0.1:${port}`, apiKey: "" });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  client = new Client({ name: "records-integration", version: "test" });
+  await Promise.all([mcp.connect(serverTransport), client.connect(clientTransport)]);
+});
+
+afterAll(async () => {
+  await client?.close();
+  for (const session of openSessions) session.destroy();
+  await new Promise<void>((resolve) => backend.close(() => resolve()));
+});
+
+describe("records roster (T05 R1)", () => {
+  it("exposes exactly the five record tools with honest annotations and no org argument", async () => {
+    const { tools } = await client.listTools();
+    expect(tools.map((t) => t.name).sort()).toEqual([...RECORD_TOOLS].sort());
+
+    const byName = new Map(tools.map((t) => [t.name, t]));
+    // Annotations are part of the DD-005 contract for external clients
+    // and the classifier; this pins the SDK actually surfacing them.
+    expect(byName.get("find_records")?.annotations).toMatchObject({ readOnlyHint: true });
+    expect(byName.get("describe_datastore")?.annotations).toMatchObject({ readOnlyHint: true });
+    expect(byName.get("update_record")?.annotations).toMatchObject({ idempotentHint: true });
+    expect(byName.get("delete_record")?.annotations).toMatchObject({
+      destructiveHint: true,
+      idempotentHint: true,
+    });
+
+    // The agent audience gets no org argument — a session-bound
+    // caller's org is server-derived, and offering the argument would
+    // only invite INVALID_ARGUMENT rejections (T05 R3).
+    for (const tool of tools) {
+      const properties = (tool.inputSchema as { properties?: Record<string, unknown> }).properties;
+      expect(Object.keys(properties ?? {}), tool.name).not.toContain("org");
+    }
+  });
+
+  it("the main roster carries the five tools WITH the org argument", async () => {
+    // Direct principals (external MCP clients) must be able to name the
+    // org their credential does not carry (DD-006 session-14 amendment).
+    const full = createServer({ serverAddress: "127.0.0.1:1", apiKey: "" });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const fullClient = new Client({ name: "records-full-roster", version: "test" });
+    await Promise.all([full.connect(serverTransport), fullClient.connect(clientTransport)]);
+    try {
+      const { tools } = await fullClient.listTools();
+      const names = tools.map((t) => t.name);
+      for (const name of RECORD_TOOLS) {
+        expect(names).toContain(name);
+      }
+      const find = tools.find((t) => t.name === "find_records");
+      const properties = (find?.inputSchema as { properties?: Record<string, unknown> })
+        .properties;
+      expect(Object.keys(properties ?? {})).toContain("org");
+    } finally {
+      await fullClient.close();
+    }
+  });
+});
+
+describe("argument → request mapping", () => {
+  it("builds the typed filter (in → is_in), order_by, and paging", async () => {
+    findResponse = () =>
+      create(RecordListSchema, {
+        records: [create(RecordEnvelopeSchema, { id: "dsr_1" })],
+        total: 1,
+        limit: 25,
+      });
+    captured.find = undefined;
+
+    const result = await callTool("find_records", {
+      datastore: "clinic",
+      collection: "bookings",
+      conditions: [
+        { field: "status", op: "eq", value: "confirmed" },
+        { field: "patient_name", op: "in", values: ["Asha", "Ravi"] },
+      ],
+      order_by: { field: "slot_start", direction: "desc" },
+      limit: 10,
+      offset: 20,
+    });
+
+    expect(result.isError).toBeFalsy();
+    // Assertion, not annotation: control-flow analysis otherwise pins the
+    // const to the `= undefined` reset above (the stub assigns in a
+    // closure the analysis cannot see across the await).
+    const req = captured.find as FindRecordsRequest | undefined;
+    expect(req?.datastore).toBe("clinic");
+    expect(req?.org).toBe(""); // agent audience: org never travels
+    expect(req?.partition).toBe(""); // partition is never a tool argument (DD-010)
+    expect(req?.filter?.conditions).toHaveLength(2);
+    expect(req?.filter?.conditions[0]).toMatchObject({ field: "status", op: 1 /* eq */ });
+    expect(req?.filter?.conditions[1]).toMatchObject({ field: "patient_name", op: 7 /* is_in */ });
+    expect(req?.filter?.conditions[1]?.values).toHaveLength(2);
+    expect(req?.orderBy).toMatchObject({ field: "slot_start", direction: 2 /* desc */ });
+    expect(req?.limit).toBe(10);
+    expect(req?.offset).toBe(20);
+
+    const body = JSON.parse(result.content[0]?.text ?? "{}") as { total?: number };
+    expect(body.total).toBe(1);
+  });
+
+  it("passes the record payload through as a Struct, untouched", async () => {
+    insertOutcome = () => create(RecordEnvelopeSchema, { id: "dsr_new" });
+    captured.insert = undefined;
+
+    const result = await callTool("insert_record", {
+      datastore: "clinic",
+      collection: "bookings",
+      record: { slot_start: "2026-07-21T04:30:00Z", patient_name: "Asha" },
+    });
+
+    expect(result.isError).toBeFalsy();
+    const req = captured.insert as InsertRecordRequest | undefined;
+    expect(req?.record).toMatchObject({
+      slot_start: "2026-07-21T04:30:00Z",
+      patient_name: "Asha",
+    });
+  });
+});
+
+describe("records error mapper (DD-005 SD-6)", () => {
+  it("passes a constraint violation through verbatim with ErrorInfo companions", async () => {
+    insertOutcome = () => {
+      throw new ConnectError("that slot is already booked", Code.AlreadyExists, undefined, [
+        {
+          desc: ErrorInfoSchema,
+          value: create(ErrorInfoSchema, {
+            reason: "CONSTRAINT_VIOLATION",
+            domain: "datastore.stigmer.ai",
+            metadata: { constraint: "one_confirmed_per_slot" },
+          }),
+        },
+      ]);
+    };
+
+    const result = await callTool("insert_record", {
+      datastore: "clinic",
+      collection: "bookings",
+      record: { slot_start: "2026-07-21T04:30:00Z", patient_name: "Ravi" },
+    });
+
+    expect(result.isError).toBe(true);
+    expect(JSON.parse(result.content[0]?.text ?? "{}")).toEqual({
+      error: "that slot is already booked",
+      code: "ALREADY_EXISTS",
+      reason: "CONSTRAINT_VIOLATION",
+      constraint: "one_confirmed_per_slot",
+    });
+  });
+
+  it("passes a permission denial through verbatim — never the shared rewrite", async () => {
+    insertOutcome = () => {
+      throw new ConnectError(
+        "you are not allowed to insert records in schedule_exceptions",
+        Code.PermissionDenied,
+        undefined,
+        [
+          {
+            desc: ErrorInfoSchema,
+            value: create(ErrorInfoSchema, {
+              reason: "VERB_DENIED",
+              domain: "datastore.stigmer.ai",
+            }),
+          },
+        ],
+      );
+    };
+
+    const result = await callTool("insert_record", {
+      datastore: "clinic",
+      collection: "schedule_exceptions",
+      record: { exception_date: "2026-07-22" },
+    });
+
+    expect(result.isError).toBe(true);
+    const body = JSON.parse(result.content[0]?.text ?? "{}") as Record<string, string>;
+    // The relayable domain bytes — NOT "Check your API key permissions".
+    expect(body.error).toBe("you are not allowed to insert records in schedule_exceptions");
+    expect(body.code).toBe("PERMISSION_DENIED");
+    expect(body.reason).toBe("VERB_DENIED");
+    expect(body.constraint).toBeUndefined();
+  });
+
+  it("delegates transport codes to the shared classifier", async () => {
+    findResponse = () => {
+      throw new ConnectError("upstream down", Code.Unavailable);
+    };
+
+    const result = await callTool("find_records", {
+      datastore: "clinic",
+      collection: "bookings",
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0]?.text).toBe(
+      "Stigmer server is unavailable. Ensure it is running and reachable.",
+    );
+  });
+});

package/src/domains/records/tools.ts

@@ -0,0 +1,206 @@
+// MCP tools for the Datastore record domain — the five agent-facing
+// record tools of DD-005: 1:1 projections of the record RPCs, with the
+// records-own error mapper (errors.ts) and honest MCP annotations (the
+// bridge's first use of annotations; the platform's own connect-time
+// classifier honors destructiveHint fail-closed for external clients,
+// while the runner-synthesized attachment is approval-free by
+// construction and never passes through that classifier).
+//
+// Two audiences, one definition (registered per roster):
+//   - "agent" (the records-only roster the runner-synthesized
+//     attachment connects to): NO `org` argument — a session-bound
+//     caller's org is server-derived from the session, and an explicit
+//     org is rejected (T05 R3), so offering the argument would only
+//     invite rejected calls.
+//   - "direct" (the main roster external MCP clients see): optional
+//     `org`, which cloud direct principals must name (their credential
+//     carries no ambient org — the DD-006 session-14 amendment). OSS
+//     resolves an empty org to the local system org.
+// `partition` is deliberately NOT a tool argument for either audience
+// (DD-010: never from tool arguments); partition-explicit work is the
+// console/CLI/SDK surface.
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+import { resolveToken, type BackendTarget } from "../client.js";
+import {
+  deleteRecord,
+  describeDatastore,
+  findRecords,
+  insertRecord,
+  updateRecord,
+  type ConditionArg,
+} from "./calls.js";
+import { recordResult } from "./errors.js";
+
+/** Which roster the tools are being registered on (see file header). */
+export type RecordToolAudience = "agent" | "direct";
+
+const ENCODINGS =
+  "Field value encodings: date YYYY-MM-DD, time HH:MM[:SS], timestamp RFC 3339 UTC " +
+  "(e.g. 2026-07-21T04:30:00Z).";
+
+const scalar = z.union([z.string(), z.number(), z.boolean()]);
+
+const conditionShape = z.object({
+  field: z
+    .string()
+    .describe("Declared field name, or a filterable system field (id, created_at, updated_at)."),
+  op: z
+    .enum(["eq", "neq", "gt", "gte", "lt", "lte", "in", "not_in", "is_null", "not_null"])
+    .describe(
+      "Comparison operator. eq/neq/in/not_in for string and enum fields; " +
+        "gt/gte/lt/lte for numeric and temporal fields; is_null/not_null for optional fields.",
+    ),
+  value: scalar
+    .nullable()
+    .optional()
+    .describe("Comparison value for scalar operators, in the field's canonical encoding."),
+  values: z.array(scalar).optional().describe("Comparison values for in / not_in."),
+});
+
+/** Register the five record tools for one audience; returns the tool names. */
+export function registerRecordTools(
+  server: McpServer,
+  target: BackendTarget,
+  audience: RecordToolAudience,
+): string[] {
+  // The org argument exists only on the direct roster (file header).
+  const orgShape: { org?: z.ZodOptional<z.ZodString> } = {};
+  if (audience === "direct") {
+    orgShape.org = z
+      .string()
+      .optional()
+      .describe(
+        "Organization that owns the datastore. Required on Stigmer Cloud; " +
+          "omit against a local backend.",
+      );
+  }
+
+  server.registerTool(
+    "describe_datastore",
+    {
+      description:
+        "Describe a datastore: its collections, field declarations and encodings, constraint " +
+        "messages, data partitions, and the verbs you are allowed to use per collection " +
+        "(empty access means you are not allowed to touch that collection). Call this before " +
+        `the first record operation against an unfamiliar datastore. ${ENCODINGS}`,
+      inputSchema: {
+        datastore: z.string().describe("Datastore slug (e.g. clinic)."),
+        ...orgShape,
+      },
+      annotations: { readOnlyHint: true },
+    },
+    (args, extra) =>
+      recordResult(`datastore "${args.datastore}"`, () =>
+        describeDatastore(target.serverAddress, resolveToken(extra, target.apiKey), args),
+      ),
+  );
+
+  server.registerTool(
+    "find_records",
+    {
+      description:
+        "Find records in a datastore collection with a typed filter (conditions are AND-combined). " +
+        "Returns records plus total/limit/offset for paging. Results are ordered by created_at " +
+        `descending unless order_by is given. ${ENCODINGS}`,
+      inputSchema: {
+        datastore: z.string().describe("Datastore slug (e.g. clinic)."),
+        ...orgShape,
+        collection: z.string().describe("Collection to query (e.g. bookings)."),
+        conditions: z
+          .array(conditionShape)
+          .optional()
+          .describe("Filter conditions, AND-combined. Omit to list all readable records."),
+        order_by: z
+          .object({
+            field: z.string().describe("Field to sort by."),
+            direction: z.enum(["asc", "desc"]).optional().describe("Sort direction (default asc)."),
+          })
+          .optional()
+          .describe("Sort order. Omit for created_at descending with id tiebreak."),
+        limit: z.number().int().optional().describe("Page size (default 25, max 100)."),
+        offset: z.number().int().optional().describe("Records to skip for paging."),
+      },
+      annotations: { readOnlyHint: true },
+    },
+    (args, extra) =>
+      recordResult(`records in "${args.datastore}/${args.collection}"`, () =>
+        findRecords(target.serverAddress, resolveToken(extra, target.apiKey), {
+          ...args,
+          conditions: args.conditions as ConditionArg[] | undefined,
+        }),
+      ),
+  );
+
+  server.registerTool(
+    "insert_record",
+    {
+      description:
+        "Insert one record into a datastore collection. System fields (id, created_at, " +
+        "updated_at, created_by) are server-stamped — never include them. Declared constraints " +
+        "are enforced by the store; a violation returns the constraint's message verbatim " +
+        "(e.g. a taken slot returns ALREADY_EXISTS — pick another, do not retry the same one). " +
+        `When uncertain whether a record already exists, find first. ${ENCODINGS}`,
+      inputSchema: {
+        datastore: z.string().describe("Datastore slug (e.g. clinic)."),
+        ...orgShape,
+        collection: z.string().describe("Collection to insert into (e.g. bookings)."),
+        record: z
+          .record(z.unknown())
+          .describe("Declared fields for the new record, in canonical encodings."),
+      },
+    },
+    (args, extra) =>
+      recordResult(`record in "${args.datastore}/${args.collection}"`, () =>
+        insertRecord(target.serverAddress, resolveToken(extra, target.apiKey), args),
+      ),
+  );
+
+  server.registerTool(
+    "update_record",
+    {
+      description:
+        "Update one record by id with a partial merge: only the supplied fields change, and an " +
+        "explicit null clears a field. Constraints are re-evaluated on the merged result. " +
+        `Returns the full updated record. ${ENCODINGS}`,
+      inputSchema: {
+        datastore: z.string().describe("Datastore slug (e.g. clinic)."),
+        ...orgShape,
+        collection: z.string().describe("Collection holding the record."),
+        id: z.string().describe("Record id (from a previous find or insert)."),
+        fields: z
+          .record(z.unknown())
+          .describe("Fields to merge. Explicit null clears a field; omitted fields keep their values."),
+      },
+      annotations: { idempotentHint: true },
+    },
+    (args, extra) =>
+      recordResult(`record "${args.id}" in "${args.datastore}/${args.collection}"`, () =>
+        updateRecord(target.serverAddress, resolveToken(extra, target.apiKey), args),
+      ),
+  );
+
+  server.registerTool(
+    "delete_record",
+    {
+      description:
+        "Delete one record by id. Returns the deleted record. Record tools never delete " +
+        "collections or datastores.",
+      inputSchema: {
+        datastore: z.string().describe("Datastore slug (e.g. clinic)."),
+        ...orgShape,
+        collection: z.string().describe("Collection holding the record."),
+        id: z.string().describe("Record id (from a previous find or insert)."),
+      },
+      annotations: { destructiveHint: true, idempotentHint: true },
+    },
+    (args, extra) =>
+      recordResult(`record "${args.id}" in "${args.datastore}/${args.collection}"`, () =>
+        deleteRecord(target.serverAddress, resolveToken(extra, target.apiKey), args),
+      ),
+  );
+
+  return ["describe_datastore", "find_records", "insert_record", "update_record", "delete_record"];
+}

package/src/gen/agent.ts

@@ -6,7 +6,7 @@
 import { generateSlug, visibilityFromString } from "./apply-runtime.js";
 import { create } from "@bufbuild/protobuf";
 import { AgentSchema, type Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
-import { AgentSpecSchema, ToolApprovalOverrideSchema, McpServerUsageSchema, McpAccessSchema, SubAgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { AgentSpecSchema, ToolApprovalOverrideSchema, McpServerUsageSchema, McpAccessSchema, SubAgentSchema, DatastoreUsageSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import { EnvVarDeclarationSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
@@ -28,6 +28,7 @@ export const AgentInputShape = {
   skill_refs: z.array(z.lazy(() => SkillRefInputSchema)).optional().describe("Skill resources providing additional knowledge to the agent."),
   sub_agents: z.array(z.lazy(() => SubAgentInputSchema)).optional().describe("Sub-agents that can be delegated to. Sub-agents can access a subset of the parent's MCP servers and tools."),
   env: z.record(z.lazy(() => EnvVarDeclarationInputSchema)).optional().describe("Environment variable declarations for this agent. Keys are variable names; values describe their metadata and optionality."),
+  datastore_usages: z.array(z.lazy(() => DatastoreUsageInputSchema)).optional().describe("Datastores this agent can use. Each entry must reference a Datastore resource by slug."),
 } as const;
 
 export const AgentInputSchema = z.object(AgentInputShape);
@@ -83,6 +84,17 @@ const EnvVarDeclarationInputSchema = z.object({
 });
 type EnvVarDeclarationInput = z.infer<typeof EnvVarDeclarationInputSchema>;
 
+const DatastoreRefInputSchema = z.object({
+  org: z.string().optional().describe("Organization that owns the referenced resource. When non-empty: must be a valid org slug (lowercase alphanumeric with hyphens, starts with a letter, 1-63 characters). Example: 'stigmer', 'acme-corp'. When empty: the reference is relative — the server resolves it to the parent resource's organization at write time. All stored and returned references always have org populated (absolute form). Use empty org for same-org references (the common case). Use explicit org for cross-org references (e.g., marketplace resources)."),
+  slug: z.string().describe("Resource slug (user-friendly identifier, unique within org). Format: lowercase alphanumeric with hyphens, must start with a letter and end with a letter or digit (e.g., 'web-search', 'code-reviewer'). Length: 2-63 characters."),
+});
+type DatastoreRefInput = z.infer<typeof DatastoreRefInputSchema>;
+
+const DatastoreUsageInputSchema = z.object({
+  datastore_ref: z.lazy(() => DatastoreRefInputSchema).describe("Reference to the Datastore resource."),
+});
+type DatastoreUsageInput = z.infer<typeof DatastoreUsageInputSchema>;
+
 
 /** Build the fully-formed Agent proto from the flat MCP apply input. */
 export function agentInputToProto(input: AgentInput): Agent {
@@ -97,6 +109,7 @@ export function agentInputToProto(input: AgentInput): Agent {
   if (input.env !== undefined) {
     for (const [k, v] of Object.entries(input.env)) spec.env[k] = envVarDeclarationInputToProto(v);
   }
+  if (input.datastore_usages !== undefined) spec.datastoreUsages = input.datastore_usages.map(datastoreUsageInputToProto);
   return Object.assign(create(AgentSchema), {
     apiVersion: "agentic.stigmer.ai/v1",
     kind: "Agent",
@@ -171,3 +184,17 @@ function envVarDeclarationInputToProto(input: EnvVarDeclarationInput) {
   return result;
 }
 
+function datastoreRefInputToProto(input: DatastoreRefInput) {
+  return create(ApiResourceReferenceSchema, {
+    org: input.org,
+    slug: input.slug,
+    kind: ApiResourceKind.datastore,
+  });
+}
+
+function datastoreUsageInputToProto(input: DatastoreUsageInput) {
+  const result = create(DatastoreUsageSchema);
+  if (input.datastore_ref !== undefined) result.datastoreRef = datastoreRefInputToProto(input.datastore_ref);
+  return result;
+}
+

package/src/gen/workflow.ts

@@ -392,7 +392,7 @@ const WorkflowTaskInputSchema: z.ZodType<WorkflowTaskInput> = z.lazy(() => z.obj
   fork: z.lazy(() => ForkTaskConfigInputSchema).optional().describe("Required when kind='fork'. ForkTaskConfig defines the configuration for fork tasks that execute branches in parallel. @internal YAML Example: - taskName: fork: branches: - branch1: do: - task1: call: http with: method: POST endpoint: uri: https://api.example.com/branch1 - branch2: do: - task2: call: http Reference: zigflow-dsl-pattern-catalog.md - Task Type 5"),
   grpc_call: z.lazy(() => GrpcCallTaskConfigInputSchema).optional().describe("Required when kind='grpc_call'. GrpcCallTaskConfig defines the configuration for grpc_call tasks that make gRPC requests. @internal YAML Example: - taskName: call: grpc with: service: 'com.example.UserService' method: 'GetUser' request: userId: ${ .userId } Reference: zigflow-dsl-pattern-catalog.md - Task Type 9"),
   http_call: z.lazy(() => HttpCallTaskConfigInputSchema).optional().describe("Required when kind='http_call'. HttpCallTaskConfig defines the configuration for http_call tasks that make HTTP requests. @internal YAML Example: - taskName: call: http with: method: POST endpoint: uri: https://api.example.com/data headers: Authorization: 'Bearer ${TOKEN}' body: field1: value Reference: zigflow-dsl-pattern-catalog.md - Task Type 2"),
-  human_input: z.lazy(() => HumanInputTaskConfigInputSchema).optional().describe("Required when kind='human_input'. HumanInputTaskConfig defines the configuration for human_input tasks that pause workflow execution to collect typed input or approval from a human reviewer, then resume based on the reviewer's response. @internal Use human_input when a workflow needs human judgment before proceeding: approvals before API calls, sign-off before publishing, confirmation before customer-impacting actions, or structured data collection from a human operator. This is a workflow-level approval gate — distinct from agent-level HITL (tool approval inside an agent session). Workflow-level gates are visible in the execution viewer as explicit tasks with input/output/timing, and they can route to different branches based on the reviewer's decision. Runtime implementation (T13) will use Temporal signals for workflow resumption. The proto definition is intentionally runtime-agnostic. The reviewer's response (selected outcome + form data) becomes the task output, accessible via export: { 'outcome': 'approve', 'form_data': { <validated form response if form_schema is set> }, 'reviewer': '<user who responded>', 'responded_at': '<ISO 8601 timestamp>' } YAML Example (approval gate with custom outcomes): - manager_approval: human_input: prompt: 'Customer-impacting incident classified as ${ $context.triage.severity }. Approve escalation?' form_schema: type: object properties: notes: type: string description: 'Optional notes for the engineering team' priority_override: type: string enum: [P1, P2, P3] outcomes: - name: approve label: 'Approve Escalation' - name: deny label: 'Reject — Not Customer-Impacting' then: re_classify - name: needs_revision label: 'Needs More Info' then: gather_more_context approvers: - 'team:engineering-leads' timeout: 86400 on_timeout: HUMAN_INPUT_TIMEOUT_ESCALATE notification_channels: - 'slack:#incident-approvals' export: as: '${ . }' YAML Example (simple binary approval, no form): - confirm_publish: human_input: prompt: 'Ready to publish ${ $context.document.title } to production?' approvers: - 'role:content-admin' timeout: 3600 on_timeout: HUMAN_INPUT_TIMEOUT_FAIL export: as: '${ . }'"),
+  human_input: z.lazy(() => HumanInputTaskConfigInputSchema).optional().describe("Required when kind='human_input'. HumanInputTaskConfig defines the configuration for human_input tasks that pause workflow execution to collect typed input or approval from a human reviewer, then resume based on the reviewer's response. @internal Use human_input when a workflow needs human judgment before proceeding: approvals before API calls, sign-off before publishing, confirmation before customer-impacting actions, or structured data collection from a human operator. This is a workflow-level approval gate — distinct from agent-level HITL (tool approval inside an agent session). Workflow-level gates are visible in the execution viewer as explicit tasks with input/output/timing, and they can route to different branches based on the reviewer's decision. Runtime implementation (T13) will use Temporal signals for workflow resumption. The proto definition is intentionally runtime-agnostic. The reviewer's response (selected outcome + form data) becomes the task output, accessible via export: { 'outcome': 'approve', 'form_data': { <validated form response if form_schema is set> }, 'reviewer': '<canonical identity of the user who responded>', 'reviewer_actor': { 'id': '<canonical identity>', 'display_name': '<human-readable name, empty when unknown>', 'email': '<email address, empty when unknown>', 'avatar': '<avatar URL, empty when unknown>' }, 'responded_at': '<ISO 8601 timestamp>' } 'reviewer' is the stable audit key (use it in switch conditions and audit joins); 'reviewer_actor' is a display snapshot stamped server-side at decision time (use it in notifications and UIs). Both are absent when the gate resolves without attribution (timeout policies, OSS single-user edition). YAML Example (approval gate with custom outcomes): - manager_approval: human_input: prompt: 'Customer-impacting incident classified as ${ $context.triage.severity }. Approve escalation?' form_schema: type: object properties: notes: type: string description: 'Optional notes for the engineering team' priority_override: type: string enum: [P1, P2, P3] outcomes: - name: approve label: 'Approve Escalation' - name: deny label: 'Reject — Not Customer-Impacting' then: re_classify - name: needs_revision label: 'Needs More Info' then: gather_more_context approvers: - 'team:engineering-leads' timeout: 86400 on_timeout: HUMAN_INPUT_TIMEOUT_ESCALATE notification_channels: - 'slack:#incident-approvals' export: as: '${ . }' YAML Example (simple binary approval, no form): - confirm_publish: human_input: prompt: 'Ready to publish ${ $context.document.title } to production?' approvers: - 'role:content-admin' timeout: 3600 on_timeout: HUMAN_INPUT_TIMEOUT_FAIL export: as: '${ . }'"),
   listen: z.lazy(() => ListenTaskConfigInputSchema).optional().describe("Required when kind='listen'. ListenTaskConfig defines the configuration for listen tasks that wait for external signals. @internal Implemented via Temporal signals. YAML Example: - taskName: listen: to: one: with: id: approval_signal type: signal Reference: zigflow-dsl-pattern-catalog.md - Task Type 7"),
   llm_call: z.lazy(() => LlmCallTaskConfigInputSchema).optional().describe("Required when kind='llm_call'. LlmCallTaskConfig defines the configuration for llm_call tasks that make direct LLM API calls without the overhead of a full agent invocation. @internal Use llm_call when the task is focused and deterministic: classification, extraction, scoring, summarization, moderation, or routing. An agent_call carries setup overhead (system prompt, tool resolution, MCP server setup, session management) that is unnecessary when all you need is a single prompt-response cycle with optional structured output. When response_schema is set, the runner requests structured output from the provider and validates the response against the schema. The on_invalid / max_retries / fallback_task fields control what happens when validation fails, using the same OnInvalidOutputPolicy enum as agent_call's output contract. YAML Example (classification with structured output): - classify_severity: call: llm with: model: 'gpt-4o-mini' system_prompt: 'You are a support ticket classifier.' prompt: 'Classify this ticket: ${ $context.ticket.description }' response_schema: type: object required: [severity, category] properties: severity: type: string enum: [low, medium, high, critical] category: type: string on_invalid: ON_INVALID_RETRY max_retries: 2 export: as: '${ . }' YAML Example (simple summarization, no schema): - summarize: call: llm with: model: 'claude-sonnet-4-5' prompt: 'Summarize in 2 sentences: ${ $context.document.text }' temperature: 0.3 max_tokens: 200 export: as: '${ . }'"),
   notification: z.lazy(() => NotificationTaskConfigInputSchema).optional().describe("Required when kind='notification'. NotificationTaskConfig defines the configuration for notification tasks that send messages to humans through channels like Slack, email, Discord, Microsoft Teams, or webhooks. @internal notification is a convenience abstraction for 'send a message to humans' — simpler and more intuitive than emit_event for common operational notification patterns. While emit_event publishes system-level CloudEvents for machine consumption, notification is purpose-built for human-readable messages with channel routing and recipient targeting. Key distinction from related task types: emit_event = system-to-system (CloudEvents, consumed by workflows/services) notification = system-to-human (Slack, email, Discord — read by people) human_input = system-to-human-to-system (waits for a response; notification is fire-and-forget) Notifications are fire-and-forget by default. The task output confirms delivery was attempted but does not wait for acknowledgment: { 'channel': 'slack', 'recipients': ['#incident-response'], 'delivered': true, 'delivered_at': '<ISO 8601 timestamp>' } For notifications that require acknowledgment or a response, use human_input instead — it pauses the workflow until a human responds. The channel field is a string (not an enum) to allow extensibility: new notification channels can be added without proto changes. The runtime (T13) resolves channel identifiers to actual notification providers configured in the workflow instance's environment. YAML Example (Slack notification): - alert_slack: notification: channel: 'slack' recipients: - '#incident-response' - '@oncall-lead' subject: 'P${ $context.triage.severity } Incident: ${ $context.ticket.title }' body: | *Severity*: ${ $context.triage.severity } *Category*: ${ $context.triage.category } *Customer Impact*: ${ $context.triage.customer_impact } *Summary*: ${ $context.agent_analysis.structured.summary } metadata: thread_ts: '${ $context.slack_thread_id }' export: as: '${ . }' YAML Example (email with template): - send_confirmation: notification: channel: 'email' recipients: - '${ $context.customer.email }' subject: 'Order ${ $context.order.number } Confirmed' body: 'Your order has been confirmed. You will receive tracking information shortly.' template: 'order-confirmation' metadata: priority: 'high' reply_to: 'support@acme.com' export: as: '${ . }'"),

package/src/http.integration.test.ts

@@ -36,6 +36,7 @@ beforeAll(async () => {
     stigmerServerAddress: "localhost:7234",
     apiKey: "",
     transport: "http",
+    roster: "full",
     httpPort: String(port),
     httpAuthEnabled: true,
     oauth: {

package/src/index.ts

@@ -6,12 +6,19 @@
 
 import { loadConfigFromEnv, validateConfig, type Config } from "./config.js";
 import { configureLogger, log } from "./logger.js";
-import { createServer, serveBoth, serveHttp, serveStdio, isNormalShutdown } from "./server.js";
+import {
+  isNormalShutdown,
+  routedServerFactory,
+  serveBoth,
+  serveHttp,
+  serveStdio,
+  stdioServer,
+} from "./server.js";
 import type { BackendTarget } from "./domains/client.js";
 
-export type { Config, OAuthConfig, Transport } from "./config.js";
+export type { Config, OAuthConfig, Roster, Transport } from "./config.js";
 export { loadConfigFromEnv, validateConfig } from "./config.js";
-export { createServer, SERVER_VERSION } from "./server.js";
+export { createServer, createRecordsServer, RECORDS_ROUTE, SERVER_VERSION } from "./server.js";
 
 /** Returns a Config populated from environment variables (no validation). */
 export function defaultConfig(): Config {
@@ -44,10 +51,10 @@ export async function run(cfg: Config, signal: AbortSignal): Promise<void> {
   try {
     switch (cfg.transport) {
       case "stdio":
-        await serveStdio(createServer(target), signal);
+        await serveStdio(stdioServer(target, cfg), signal);
         break;
       case "http":
-        await serveHttp(() => createServer(target), cfg, signal);
+        await serveHttp(routedServerFactory(target), cfg, signal);
         break;
       case "both":
         await serveBoth(target, cfg, signal);