@retinue/agentkit 0.1.0

package/dist/graphql/resolvers.js

@@ -0,0 +1,253 @@
+/**
+ * Thin GraphQL resolvers — `docs/06` → "Resolvers are thin: authenticate, validate, construct
+ * execution context and call platform services." The host's GraphQL server builds the execution
+ * context (from its auth) and puts it on the resolver context; every resolver here just validates
+ * shape and delegates to a service. No business logic lives in this layer.
+ */
+import { DEFAULT_WARN_AT, describeWindow } from "../usage/index.js";
+import { asId } from "../core/ids.js";
+import { startOrEnqueueRun } from "../runtime/index.js";
+import { openRunEventStream } from "../runtime/index.js";
+/** Serialize a stored Run to the GraphQL RunStatus enum (underscores, not hyphens). */
+const runStatus = (status) => status.replace(/-/g, "_");
+/**
+ * `conversationId` is nullable here since #198 — a run can belong to no conversation.
+ *
+ * Null, never a placeholder. A client that receives an empty string or a synthetic id would key a cache by it
+ * and group unrelated automations together.
+ */
+const toRun = (run) => ({
+    id: run.id,
+    conversationId: run.conversationId,
+    status: runStatus(run.status),
+    createdAt: run.createdAt,
+    finishedAt: run.finishedAt ?? null,
+});
+export const createResolvers = (deps) => {
+    const channelFor = deps.channelFor ?? ((id) => `conversation:${id}`);
+    const tid = (ctx) => ctx.execution.tenantId;
+    /**
+     * The quota state, from the guard rather than recomputed.
+     *
+     * Asking the guard means the panel's warning and the admission decision are the same computation. A UI that
+     * recomputed a threshold would eventually show "you are fine" while a run is being refused, which is worse
+     * than showing nothing.
+     */
+    const quotaViewFor = async (guard, execution) => {
+        const decision = await guard.admit(execution);
+        const limits = await guard.limits(execution);
+        if (limits.length === 0)
+            return null;
+        /**
+         * The **binding** limit, which is the first — shortest span (#182).
+         *
+         * Several limits can apply at once and this view describes one, because that is the shape the schema has and
+         * a client rendering "you have used X of Y" wants the Y that will stop them soonest. `usageReport` is the
+         * wrong place to widen: a caller that wants all of them should ask for all of them.
+         */
+        const binding = limits[0];
+        return {
+            window: describeWindow(binding.window),
+            // Null for a rolling window: no calendar period describes one, and naming the closest would be wrong
+            // rather than approximate.
+            period: binding.window.kind === "calendar" ? binding.window.period : null,
+            modelId: binding.modelId ?? null,
+            costLimitMinorUnits: binding.costMinorUnits ?? null,
+            inputTokenLimit: binding.inputTokens ?? null,
+            outputTokenLimit: binding.outputTokens ?? null,
+            warnAt: binding.warnAt ?? DEFAULT_WARN_AT,
+            warning: decision.admitted && decision.warnings.length > 0,
+            exceeded: !decision.admitted,
+        };
+    };
+    return {
+        Query: {
+            async conversations(_, args, ctx) {
+                return deps.conversations.list({ tenantId: tid(ctx), limit: args.limit, ...(args.cursor ? { cursor: args.cursor } : {}) });
+            },
+            async conversation(_, args, ctx) {
+                return deps.conversations.findById({ tenantId: tid(ctx), id: asId(args.id) });
+            },
+            async run(_, args, ctx) {
+                const run = await deps.runs.findById({ tenantId: tid(ctx), id: asId(args.id) });
+                return run ? toRun(run) : null;
+            },
+            async toolCatalog(_, args, ctx) {
+                return deps.toolRegistry.catalog(ctx.execution, args);
+            },
+            async usage(_, args, ctx) {
+                return deps.usage.totals({ tenantId: tid(ctx), ...(args.runId ? { runId: asId(args.runId) } : {}) });
+            },
+            /**
+             * The spend panel's one query (#140).
+             *
+             * Headline totals and buckets come from the **rollups**, so a page load never scans raw records however
+             * much a tenant has used. Breakdowns come from the ledger over the same bounded range — a deliberate
+             * trade documented on `UsageStore.breakdown`.
+             *
+             * Everything in one resolver so a panel cannot show a total from one moment and a breakdown from another;
+             * the discrepancy would look like a bug in the numbers rather than in the fetching.
+             */
+            async usageReport(_, args, ctx) {
+                const period = args.period === "hour" ? "hour" : "day";
+                const limit = Math.min(Math.max(1, args.breakdownLimit ?? 10), 50);
+                const scope = { tenantId: tid(ctx), period, from: args.from, to: args.to };
+                // Absent rollup support is not an error: a deployment can run without the rollup job and still answer
+                // from the ledger. Reported as empty buckets rather than a failure, because a panel with no chart is
+                // usable and a panel with an error is not.
+                const buckets = deps.rollups === undefined ? { items: [] } : await deps.rollups.list({ ...scope, limit: 400 });
+                const totals = deps.rollups === undefined
+                    ? await deps.usage.totals({ tenantId: tid(ctx) })
+                    : await deps.rollups.sum(scope);
+                const [byModel, byConversation] = await Promise.all([
+                    deps.usage.breakdown({ tenantId: tid(ctx), from: args.from, to: args.to, by: "model", limit }),
+                    deps.usage.breakdown({ tenantId: tid(ctx), from: args.from, to: args.to, by: "conversation", limit }),
+                ]);
+                // The quota state as the *server* computes it, so a UI cannot disagree with the enforcement. Absent
+                // when no limit is configured, which means unbounded — a UI must show "no limit" rather than a full bar.
+                const quota = deps.quota === undefined ? null : await quotaViewFor(deps.quota, ctx.execution);
+                return {
+                    period,
+                    from: args.from,
+                    to: args.to,
+                    totals,
+                    buckets: buckets.items.map((b) => ({
+                        bucketStart: b.bucketStart,
+                        currency: b.currency,
+                        totals: b,
+                    })),
+                    byModel,
+                    byConversation,
+                    quota,
+                    // The currency of the buckets in range. Empty when there is no usage — a period with no spend has no
+                    // currency, and claiming one would be inventing a fact for a UI to format with.
+                    currency: buckets.items.find((b) => b.currency !== "")?.currency ?? "",
+                };
+            },
+            /**
+             * #163. Shaped for rendering: the optional fields are filled in rather than passed through, because a
+             * client that has to treat `null` as "one choice" and `undefined` as "one choice" and `false` as "one
+             * choice" will eventually treat one of them as "several".
+             */
+            async pendingQuestion(_, args, ctx) {
+                const question = await deps.questions.pending({ tenantId: tid(ctx), runId: asId(args.runId) });
+                if (question === null)
+                    return null;
+                return {
+                    interactionId: question.id,
+                    runId: question.runId,
+                    createdAt: question.createdAt,
+                    questions: question.questions.map((q) => ({
+                        key: q.key,
+                        prompt: q.prompt,
+                        options: q.options ?? [],
+                        multiple: q.multiple === true,
+                        // Free text with no options is the only sensible reading of a question that offers no choices, so
+                        // it is implied there rather than left to each client to infer.
+                        allowOther: q.allowOther === true || (q.options ?? []).length === 0,
+                    })),
+                };
+            },
+            /** #163, the mirror of `pendingQuestion`. Wired the same way so the two cannot drift. */
+            async pendingApproval(_, args, ctx) {
+                const approval = await deps.approvals.pending({ tenantId: tid(ctx), runId: asId(args.runId) });
+                if (approval === null)
+                    return null;
+                return {
+                    interactionId: approval.id,
+                    runId: approval.runId,
+                    toolName: approval.toolName,
+                    summary: approval.summary,
+                    riskCategory: approval.riskCategory,
+                    expiresAt: approval.expiresAt,
+                    normalizedInput: approval.normalizedInput,
+                };
+            },
+            async conversationContext(_, args, ctx) {
+                if (!deps.inspectContext)
+                    return null;
+                return deps.inspectContext(ctx.execution, {
+                    conversationId: asId(args.conversationId),
+                    ...(args.runId ? { runId: asId(args.runId) } : {}),
+                });
+            },
+        },
+        Mutation: {
+            async createConversation(_, args, ctx) {
+                return deps.conversations.create({ tenantId: tid(ctx), id: asId(args.id), title: args.title });
+            },
+            async renameConversation(_, args, ctx) {
+                return deps.conversations.update({ tenantId: tid(ctx), id: asId(args.id), expectedVersion: args.expectedVersion, patch: { title: args.title } });
+            },
+            async archiveConversation(_, args, ctx) {
+                return deps.conversations.update({ tenantId: tid(ctx), id: asId(args.id), expectedVersion: args.expectedVersion, patch: { archivedAt: new Date().toISOString() } });
+            },
+            async deleteConversation(_, args, ctx) {
+                await deps.conversations.softDelete({ tenantId: tid(ctx), id: asId(args.id) });
+                return true;
+            },
+            async sendMessage(_, args, ctx) {
+                const conversationId = asId(args.conversationId);
+                const runId = asId(args.runId);
+                // #139, AC-2: the quota check is *here*, before the conversation is claimed and before anything is
+                // enqueued — so a refused run leaves no slot held, no job on the queue, and no partial answer. A limit
+                // enforced mid-run leaves a half-written response and a user who has to guess whether to retry.
+                //
+                // Optional, because a deployment with no limits configured is valid; when it is absent nothing is
+                // checked, which is the same as an unbounded limit.
+                if (deps.quota !== undefined)
+                    await deps.quota.assertAdmitted(ctx.execution);
+                const started = await startOrEnqueueRun(deps.coordinator, { tenantId: tid(ctx), conversationId, runId });
+                if (started === "started")
+                    await deps.dispatcher.enqueueRun({ tenantId: tid(ctx), runId });
+                const run = await deps.runs.findById({ tenantId: tid(ctx), id: runId });
+                return run ? toRun(run) : { id: runId, conversationId, status: started === "started" ? "running" : "queued", createdAt: new Date().toISOString(), finishedAt: null };
+            },
+            async cancelRun(_, args, ctx) {
+                await deps.runs.requestCancel({ tenantId: tid(ctx), id: asId(args.runId), now: new Date().toISOString() });
+                return true;
+            },
+            async answerQuestion(_, args, ctx) {
+                const { resumed } = await deps.questions.answer({
+                    tenantId: tid(ctx),
+                    interactionId: asId(args.input.interactionId),
+                    runId: asId(args.input.runId),
+                    answers: args.input.answers,
+                });
+                return resumed;
+            },
+            async decideApproval(_, args, ctx) {
+                const { resumed } = await deps.approvals.decide({
+                    tenantId: tid(ctx),
+                    interactionId: asId(args.input.interactionId),
+                    runId: asId(args.input.runId),
+                    decision: args.input.decision,
+                });
+                return resumed;
+            },
+        },
+        Subscription: {
+            runEvents: {
+                subscribe(_, args, ctx) {
+                    return openRunEventStream({
+                        tenantId: tid(ctx),
+                        runId: asId(args.runId),
+                        channel: channelFor(asId(args.conversationId)),
+                        after: args.after ?? 0,
+                        log: deps.eventLog,
+                        live: deps.live,
+                    });
+                },
+                // The transport delivers each event as { runEvents: { type, runId, sequence, occurredAt, payload } }.
+                resolve: (event) => ({
+                    type: event.type,
+                    runId: event.runId,
+                    sequence: event.sequence,
+                    occurredAt: event.occurredAt,
+                    payload: event,
+                }),
+            },
+        },
+    };
+};
+//# sourceMappingURL=resolvers.js.map

package/dist/graphql/schema.d.ts

@@ -0,0 +1,11 @@
+/**
+ * GraphQL schema (SDL) — `docs/06-graphql-and-frontend.md` → GraphQL boundary.
+ *
+ * The package ships the schema as SDL plus a thin resolver map (see `./resolvers`), so a host can
+ * mount it on any GraphQL server (Yoga, Apollo, Mercurius) without the library taking a server
+ * dependency. Resolvers stay thin: authenticate, validate, build the execution context, call a
+ * platform service. Subscriptions carry the stable `RunEvent` set and support resuming after a
+ * cursor via `openRunEventStream`.
+ */
+export declare const typeDefs = "\n  scalar JSON\n  scalar DateTime\n\n  type Conversation {\n    id: ID!\n    title: String!\n    version: Int!\n    archivedAt: DateTime\n    createdAt: DateTime!\n    updatedAt: DateTime!\n  }\n\n  type ConversationPage {\n    items: [Conversation!]!\n    nextCursor: String\n  }\n\n  enum RunStatus {\n    queued\n    running\n    waiting_for_question\n    waiting_for_approval\n    retry_pending\n    completed\n    failed\n    cancelled\n  }\n\n  type Run {\n    id: ID!\n    \"Null for a run that belongs to no conversation \u2014 a triggered automation rather than a chat turn (#198).\"\n    conversationId: ID\n    status: RunStatus!\n    createdAt: DateTime!\n    finishedAt: DateTime\n  }\n\n  type ToolCatalogEntry {\n    name: String!\n    label: String!\n    description: String!\n    category: String!\n    effect: String!\n  }\n\n  type ToolCatalog {\n    preloaded: [JSON!]!\n    discoverable: [ToolCatalogEntry!]!\n    meta: [ToolCatalogEntry!]!\n  }\n\n  type UsageTotals {\n    inputTokens: Int!\n    outputTokens: Int!\n    cachedInputTokens: Int!\n    costMinorUnits: Int!\n    eventCount: Int!\n  }\n\n  \"One period's consumption. #139's rollups, so a chart never scans raw records.\"\n  type UsageBucket {\n    bucketStart: String!\n    totals: UsageTotals!\n    currency: String!\n  }\n\n  \"Consumption grouped by model or conversation over the requested range.\"\n  type UsageBreakdownEntry {\n    key: String!\n    totals: UsageTotals!\n  }\n\n  \"\"\"\n  Where the tenant stands against its limit.\n\n  Absent when no limit is configured \u2014 which means unbounded, not zero. A UI must show \"no limit set\"\n  rather than a full bar.\n  \"\"\"\n  type UsageQuota {\n    \"\"\"\n    The window in words \u2014 \"the day\", \"any 5 hours\" (#181).\n\n    period stayed for the calendar case and is **null** for a rolling window, because no RollupPeriod describes\n    one and returning \"hour\" for a five-hour window would be a wrong answer rather than a missing one. A client\n    rendering the window reads this field; one keying a chart by bucket reads period and correctly finds nothing\n    to key by.\n    \"\"\"\n    window: String!\n    period: String\n    \"The model this limit covers, or null for any model (#182).\"\n    modelId: String\n    costLimitMinorUnits: Int\n    inputTokenLimit: Int\n    outputTokenLimit: Int\n    \"The fraction of the limit at which a warning shows. Sent so the UI cannot disagree with the server.\"\n    warnAt: Float!\n    \"True once any dimension is past warnAt and still admitted.\"\n    warning: Boolean!\n    \"True once any dimension has reached its limit, so work is being refused.\"\n    exceeded: Boolean!\n  }\n\n  \"\"\"\n  The usage report a spend panel renders.\n\n  One query rather than several, so a panel cannot show a total from one moment and a breakdown from another.\n  \"\"\"\n  type UsageReport {\n    period: String!\n    from: String!\n    to: String!\n    totals: UsageTotals!\n    buckets: [UsageBucket!]!\n    byModel: [UsageBreakdownEntry!]!\n    byConversation: [UsageBreakdownEntry!]!\n    quota: UsageQuota\n    currency: String!\n  }\n\n  \"A single transport event; payload carries the typed part / lifecycle detail.\"\n  type RunEvent {\n    type: String!\n    runId: ID!\n    sequence: Int!\n    occurredAt: DateTime!\n    payload: JSON!\n  }\n\n  \"\"\"\n  One question put to a person, as it must be *rendered* \u2014 #163.\n\n  The event that suspends a run carries only an interactionId, deliberately: events are thin, and a payload\n  that duplicated the question would be a second copy to keep in step with the stored one. But nothing exposed\n  the stored one either, so a client could answer a question it had no way to display. The example's picker\n  rendered an empty text box next to \"The assistant has a question\", which is the whole gap in one screenshot.\n  \"\"\"\n  type PendingQuestionSpec {\n    \"Stable key the answer is filed under.\"\n    key: String!\n    prompt: String!\n    \"A short closed list, when there is one. Empty means free text.\"\n    options: [String!]!\n    \"Several choices are allowed, not one.\"\n    multiple: Boolean!\n    \"Free text is accepted alongside the options.\"\n    allowOther: Boolean!\n  }\n\n  type PendingQuestion {\n    interactionId: ID!\n    runId: ID!\n    questions: [PendingQuestionSpec!]!\n    createdAt: DateTime!\n  }\n\n  \"\"\"\n  The approval a run is parked on \u2014 the read side of decideApproval (#163).\n\n  The same gap as pendingQuestion and milder rather than absent: approval.requested also carries only an\n  interaction id, so a client had no summary to show and fell back to a generic \"Run a tool?\". Asking someone\n  to authorise an action the card cannot name is how approval becomes a reflex.\n  \"\"\"\n  type PendingApprovalDetail {\n    interactionId: ID!\n    runId: ID!\n    toolName: String!\n    \"One line a person can decide on, written by the host's summarizer.\"\n    summary: String!\n    riskCategory: String!\n    expiresAt: DateTime!\n    \"The arguments the approval is for, so what runs is what was shown.\"\n    normalizedInput: JSON!\n  }\n\n  input QuestionAnswerInput {\n    interactionId: ID!\n    runId: ID!\n    answers: JSON!\n  }\n\n  input ApprovalDecisionInput {\n    interactionId: ID!\n    runId: ID!\n    decision: String!\n  }\n\n  \"A section that shaped a turn's prompt \u2014 for the context inspector (#39).\"\n  type InspectedSection {\n    title: String!\n    providerId: String!\n    kind: String!\n    provenance: String!\n    estimatedTokens: Int!\n    sensitivity: String!\n    included: Boolean!\n    prunedReason: String\n  }\n\n  type ContextInspection {\n    sections: [InspectedSection!]!\n    totalTokens: Int!\n    budget: JSON!\n  }\n\n  type Query {\n    conversations(limit: Int!, cursor: String): ConversationPage!\n    conversation(id: ID!): Conversation\n    run(id: ID!): Run\n    toolCatalog(preloaded: [String!]!, categories: [String!]!, excluded: [String!]!): ToolCatalog!\n    usage(runId: ID): UsageTotals!\n    \"\"\"\n    Consumption and cost by period, with breakdowns and quota state (#140).\n\n    An extension of the usage query rather than a second endpoint: a panel showing a total from one query and a\n    breakdown from another can show two moments at once, and the discrepancy looks like a bug in the numbers.\n    \"\"\"\n    usageReport(period: String!, from: String!, to: String!, breakdownLimit: Int): UsageReport!\n    \"What context shaped a turn \u2014 attributes memory/tools/history that influenced the prompt.\"\n    conversationContext(conversationId: ID!, runId: ID): ContextInspection\n    \"\"\"\n    The question a run is parked on, or null \u2014 the read side of answerQuestion (#163).\n\n    Null covers both \"this run was never asked anything\" and \"it has been answered already\", because a client\n    has the same thing to do in either case: show no picker. A run that is waiting is the only state with a\n    question to render.\n    \"\"\"\n    pendingQuestion(runId: ID!): PendingQuestion\n    \"The approval a run is parked on, or null (#163).\"\n    pendingApproval(runId: ID!): PendingApprovalDetail\n  }\n\n  type Mutation {\n    createConversation(id: ID!, title: String!): Conversation!\n    renameConversation(id: ID!, expectedVersion: Int!, title: String!): Conversation!\n    archiveConversation(id: ID!, expectedVersion: Int!): Conversation!\n    deleteConversation(id: ID!): Boolean!\n    sendMessage(conversationId: ID!, runId: ID!): Run!\n    cancelRun(runId: ID!): Boolean!\n    answerQuestion(input: QuestionAnswerInput!): Boolean!\n    decideApproval(input: ApprovalDecisionInput!): Boolean!\n  }\n\n  type Subscription {\n    \"Conversation/run events, resumable after a cursor (sequence).\"\n    runEvents(runId: ID!, conversationId: ID!, after: Int): RunEvent!\n  }\n";
+//# sourceMappingURL=schema.d.ts.map

package/dist/graphql/schema.js

@@ -0,0 +1,258 @@
+/**
+ * GraphQL schema (SDL) — `docs/06-graphql-and-frontend.md` → GraphQL boundary.
+ *
+ * The package ships the schema as SDL plus a thin resolver map (see `./resolvers`), so a host can
+ * mount it on any GraphQL server (Yoga, Apollo, Mercurius) without the library taking a server
+ * dependency. Resolvers stay thin: authenticate, validate, build the execution context, call a
+ * platform service. Subscriptions carry the stable `RunEvent` set and support resuming after a
+ * cursor via `openRunEventStream`.
+ */
+export const typeDefs = /* GraphQL */ `
+  scalar JSON
+  scalar DateTime
+
+  type Conversation {
+    id: ID!
+    title: String!
+    version: Int!
+    archivedAt: DateTime
+    createdAt: DateTime!
+    updatedAt: DateTime!
+  }
+
+  type ConversationPage {
+    items: [Conversation!]!
+    nextCursor: String
+  }
+
+  enum RunStatus {
+    queued
+    running
+    waiting_for_question
+    waiting_for_approval
+    retry_pending
+    completed
+    failed
+    cancelled
+  }
+
+  type Run {
+    id: ID!
+    "Null for a run that belongs to no conversation — a triggered automation rather than a chat turn (#198)."
+    conversationId: ID
+    status: RunStatus!
+    createdAt: DateTime!
+    finishedAt: DateTime
+  }
+
+  type ToolCatalogEntry {
+    name: String!
+    label: String!
+    description: String!
+    category: String!
+    effect: String!
+  }
+
+  type ToolCatalog {
+    preloaded: [JSON!]!
+    discoverable: [ToolCatalogEntry!]!
+    meta: [ToolCatalogEntry!]!
+  }
+
+  type UsageTotals {
+    inputTokens: Int!
+    outputTokens: Int!
+    cachedInputTokens: Int!
+    costMinorUnits: Int!
+    eventCount: Int!
+  }
+
+  "One period's consumption. #139's rollups, so a chart never scans raw records."
+  type UsageBucket {
+    bucketStart: String!
+    totals: UsageTotals!
+    currency: String!
+  }
+
+  "Consumption grouped by model or conversation over the requested range."
+  type UsageBreakdownEntry {
+    key: String!
+    totals: UsageTotals!
+  }
+
+  """
+  Where the tenant stands against its limit.
+
+  Absent when no limit is configured — which means unbounded, not zero. A UI must show "no limit set"
+  rather than a full bar.
+  """
+  type UsageQuota {
+    """
+    The window in words — "the day", "any 5 hours" (#181).
+
+    period stayed for the calendar case and is **null** for a rolling window, because no RollupPeriod describes
+    one and returning "hour" for a five-hour window would be a wrong answer rather than a missing one. A client
+    rendering the window reads this field; one keying a chart by bucket reads period and correctly finds nothing
+    to key by.
+    """
+    window: String!
+    period: String
+    "The model this limit covers, or null for any model (#182)."
+    modelId: String
+    costLimitMinorUnits: Int
+    inputTokenLimit: Int
+    outputTokenLimit: Int
+    "The fraction of the limit at which a warning shows. Sent so the UI cannot disagree with the server."
+    warnAt: Float!
+    "True once any dimension is past warnAt and still admitted."
+    warning: Boolean!
+    "True once any dimension has reached its limit, so work is being refused."
+    exceeded: Boolean!
+  }
+
+  """
+  The usage report a spend panel renders.
+
+  One query rather than several, so a panel cannot show a total from one moment and a breakdown from another.
+  """
+  type UsageReport {
+    period: String!
+    from: String!
+    to: String!
+    totals: UsageTotals!
+    buckets: [UsageBucket!]!
+    byModel: [UsageBreakdownEntry!]!
+    byConversation: [UsageBreakdownEntry!]!
+    quota: UsageQuota
+    currency: String!
+  }
+
+  "A single transport event; payload carries the typed part / lifecycle detail."
+  type RunEvent {
+    type: String!
+    runId: ID!
+    sequence: Int!
+    occurredAt: DateTime!
+    payload: JSON!
+  }
+
+  """
+  One question put to a person, as it must be *rendered* — #163.
+
+  The event that suspends a run carries only an interactionId, deliberately: events are thin, and a payload
+  that duplicated the question would be a second copy to keep in step with the stored one. But nothing exposed
+  the stored one either, so a client could answer a question it had no way to display. The example's picker
+  rendered an empty text box next to "The assistant has a question", which is the whole gap in one screenshot.
+  """
+  type PendingQuestionSpec {
+    "Stable key the answer is filed under."
+    key: String!
+    prompt: String!
+    "A short closed list, when there is one. Empty means free text."
+    options: [String!]!
+    "Several choices are allowed, not one."
+    multiple: Boolean!
+    "Free text is accepted alongside the options."
+    allowOther: Boolean!
+  }
+
+  type PendingQuestion {
+    interactionId: ID!
+    runId: ID!
+    questions: [PendingQuestionSpec!]!
+    createdAt: DateTime!
+  }
+
+  """
+  The approval a run is parked on — the read side of decideApproval (#163).
+
+  The same gap as pendingQuestion and milder rather than absent: approval.requested also carries only an
+  interaction id, so a client had no summary to show and fell back to a generic "Run a tool?". Asking someone
+  to authorise an action the card cannot name is how approval becomes a reflex.
+  """
+  type PendingApprovalDetail {
+    interactionId: ID!
+    runId: ID!
+    toolName: String!
+    "One line a person can decide on, written by the host's summarizer."
+    summary: String!
+    riskCategory: String!
+    expiresAt: DateTime!
+    "The arguments the approval is for, so what runs is what was shown."
+    normalizedInput: JSON!
+  }
+
+  input QuestionAnswerInput {
+    interactionId: ID!
+    runId: ID!
+    answers: JSON!
+  }
+
+  input ApprovalDecisionInput {
+    interactionId: ID!
+    runId: ID!
+    decision: String!
+  }
+
+  "A section that shaped a turn's prompt — for the context inspector (#39)."
+  type InspectedSection {
+    title: String!
+    providerId: String!
+    kind: String!
+    provenance: String!
+    estimatedTokens: Int!
+    sensitivity: String!
+    included: Boolean!
+    prunedReason: String
+  }
+
+  type ContextInspection {
+    sections: [InspectedSection!]!
+    totalTokens: Int!
+    budget: JSON!
+  }
+
+  type Query {
+    conversations(limit: Int!, cursor: String): ConversationPage!
+    conversation(id: ID!): Conversation
+    run(id: ID!): Run
+    toolCatalog(preloaded: [String!]!, categories: [String!]!, excluded: [String!]!): ToolCatalog!
+    usage(runId: ID): UsageTotals!
+    """
+    Consumption and cost by period, with breakdowns and quota state (#140).
+
+    An extension of the usage query rather than a second endpoint: a panel showing a total from one query and a
+    breakdown from another can show two moments at once, and the discrepancy looks like a bug in the numbers.
+    """
+    usageReport(period: String!, from: String!, to: String!, breakdownLimit: Int): UsageReport!
+    "What context shaped a turn — attributes memory/tools/history that influenced the prompt."
+    conversationContext(conversationId: ID!, runId: ID): ContextInspection
+    """
+    The question a run is parked on, or null — the read side of answerQuestion (#163).
+
+    Null covers both "this run was never asked anything" and "it has been answered already", because a client
+    has the same thing to do in either case: show no picker. A run that is waiting is the only state with a
+    question to render.
+    """
+    pendingQuestion(runId: ID!): PendingQuestion
+    "The approval a run is parked on, or null (#163)."
+    pendingApproval(runId: ID!): PendingApprovalDetail
+  }
+
+  type Mutation {
+    createConversation(id: ID!, title: String!): Conversation!
+    renameConversation(id: ID!, expectedVersion: Int!, title: String!): Conversation!
+    archiveConversation(id: ID!, expectedVersion: Int!): Conversation!
+    deleteConversation(id: ID!): Boolean!
+    sendMessage(conversationId: ID!, runId: ID!): Run!
+    cancelRun(runId: ID!): Boolean!
+    answerQuestion(input: QuestionAnswerInput!): Boolean!
+    decideApproval(input: ApprovalDecisionInput!): Boolean!
+  }
+
+  type Subscription {
+    "Conversation/run events, resumable after a cursor (sequence)."
+    runEvents(runId: ID!, conversationId: ID!, after: Int): RunEvent!
+  }
+`;
+//# sourceMappingURL=schema.js.map

package/dist/graphql/sse.d.ts

@@ -0,0 +1,77 @@
+/**
+ * SSE transport adapter — `docs/06` (embedded-profile streaming). A thin mapping from the
+ * transport-neutral `RunEvent` stream to Server-Sent Events frames. It takes no HTTP-framework
+ * dependency: `sseFrames` yields ready-to-write text frames, and `openRunEventSse` composes the
+ * reconnect stream (catch-up + live) with SSE encoding. The `Last-Event-ID` header a browser
+ * resends on reconnect maps directly to the run event `sequence`, so resuming loses no events.
+ */
+import type { RunEvent, RunEventLog } from "../core/events.js";
+import type { ConversationId, RunId, TenantId } from "../core/ids.js";
+import { type LiveEventSource } from "../runtime/index.js";
+/**
+ * The GraphQL field the frames are shaped for.
+ *
+ * Hard-coded to match the SDL's `runEvents` subscription, because that is the selection a client made.
+ * A client that *aliased* the field would look for its alias and not find it — see the open question
+ * on #111; the adapter has no way to know the alias.
+ */
+export declare const SSE_RESULT_FIELD = "runEvents";
+/**
+ * Encode one event as a graphql-sse `next` frame.
+ *
+ * `docs/extraction/twenty-sdk-comparison.md` records the decision: *"Match the `graphql-sse` framing
+ * rather than inventing a bespoke SSE protocol"* — twenty-sdk already streams GraphQL over graphql-sse,
+ * so a client can consume this unmodified. This previously emitted `event: <RunEvent.type>` with a raw
+ * `RunEvent` as `data`, which no graphql-sse client understands.
+ *
+ * The `id:` line keeps carrying `RunEvent.sequence`, which is what makes `Last-Event-ID` resume work.
+ *
+ * **A failed run is a `next` frame, not an error frame**, and that is deliberate. `run.failed` is a
+ * durable event with a sequence, sitting in the log like any other. Delivering it as a protocol-level
+ * error would leave it with no `id:` — so `Last-Event-ID` could not resume past it, and a reconnecting
+ * client would never learn the run ended. An `ExecutionResult` may carry both `data` and `errors`, so
+ * the event travels in `data` and the platform error in `errors`: clients surface it through their
+ * normal error path (which is what AC-3 is for) and resume keeps working.
+ */
+export declare const toSseFrame: (event: RunEvent) => string;
+/**
+ * The terminating frame.
+ *
+ * graphql-sse's distinct-connections mode uses `event: complete` to say the response is finished. A
+ * stream that simply stops is indistinguishable from a truncated one, and a client cannot tell whether
+ * to reconnect.
+ */
+export declare const SSE_COMPLETE_FRAME = "event: complete\ndata: \n\n";
+/**
+ * A stream-level failure, in the protocol's error shape.
+ *
+ * Distinct from a failed *run*: there is no sequence to preserve and nothing to resume to, so this is
+ * genuinely a protocol error rather than an event.
+ */
+export declare const sseErrorFrame: (message: string) => string;
+/** Parse a browser `Last-Event-ID` header into a resume cursor. Missing/invalid ⇒ 0 (from start). */
+export declare const cursorFromLastEventId: (lastEventId: string | null | undefined) => number;
+/**
+ * Map a `RunEvent` async stream to graphql-sse text frames, terminated by `complete`.
+ *
+ * The `complete` frame is emitted in a `finally`, so it is sent whether the stream ended on a terminal
+ * event or because the consumer stopped — a client should be told the response is over either way.
+ */
+export declare function sseFrames(events: AsyncIterable<RunEvent>): AsyncIterable<string>;
+/**
+ * Open a resumable SSE stream for a run: catch up from the durable log after `after`, then follow
+ * live, encoded as SSE frames. Ends on the run's terminal event.
+ */
+export declare const openRunEventSse: (input: {
+    readonly tenantId: TenantId;
+    readonly runId: RunId;
+    readonly conversationId: ConversationId;
+    readonly after: number;
+    readonly log: RunEventLog;
+    readonly live: LiveEventSource;
+    readonly channelFor?: (conversationId: ConversationId) => string;
+    readonly signal?: {
+        readonly aborted: boolean;
+    };
+}) => AsyncIterable<string>;
+//# sourceMappingURL=sse.d.ts.map