@flytedesk/app-kit 0.3.0 → 0.4.0

package/dist/bigquery/types.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Structural (duck-typed) subset of `@google-cloud/bigquery`'s own BigQuery /
+ * Job / Dataset / Table classes that this module actually calls — mirrors
+ * src/trace/types.ts's TracePrismaClient boundary: deliberately NOT a
+ * dependency on `@google-cloud/bigquery` (this package has no hard dependency
+ * on any GCP SDK), so a real `new BigQuery()` instance satisfies BigQueryLike
+ * directly (TypeScript structural typing — its Job/Dataset/Table classes carry
+ * every member below), and a test fake can implement just this surface without
+ * mocking the SDK's own internals. AK-11: extracted from media-planner's
+ * `apps/api/src/services/inventoryWarehouse.ts`, generalizing the
+ * `@google-cloud/bigquery` calls it made; inventory-specific SQL stays behind
+ * in media-planner.
+ */
+/** One structured error entry, same shape the Google APIs client library
+ *  attaches to a rejected job promise's `.errors` array. */
+export interface BigQueryApiErrorDetail {
+    reason?: string;
+    message?: string;
+    location?: string;
+}
+export interface BigQueryJobStatus {
+    state?: string;
+    errorResult?: BigQueryApiErrorDetail | null;
+    errors?: BigQueryApiErrorDetail[];
+}
+export interface BigQueryJobStatistics {
+    query?: {
+        totalBytesProcessed?: string | number;
+        totalBytesBilled?: string | number;
+        cacheHit?: boolean;
+    };
+}
+export interface BigQueryJobMetadata {
+    id?: string;
+    status?: BigQueryJobStatus;
+    statistics?: BigQueryJobStatistics;
+    configuration?: {
+        labels?: Record<string, string>;
+        dryRun?: boolean;
+    };
+}
+export interface BigQueryQueryResultsOptions {
+    maxResults?: number;
+    pageToken?: string;
+}
+/** The next-page cursor `Job#getQueryResults` hands back as its second tuple
+ *  element — `null` once there are no more pages. */
+export type BigQueryNextQuery = {
+    pageToken?: string;
+} | null;
+export interface BigQueryJobLike {
+    id: string;
+    getMetadata(): Promise<[BigQueryJobMetadata, unknown]>;
+    getQueryResults<T = Record<string, unknown>>(options?: BigQueryQueryResultsOptions): Promise<[T[], BigQueryNextQuery, unknown]>;
+}
+export interface BigQueryCreateQueryJobOptions {
+    query: string;
+    /** Positional (`?`) or named (`@name`) query parameters. */
+    params?: unknown[] | Record<string, unknown>;
+    /** Only needed when the SDK can't infer a param's BigQuery type. */
+    types?: unknown[] | Record<string, string>;
+    labels?: Record<string, string>;
+    dryRun?: boolean;
+    location?: string;
+    maxResults?: number;
+    jobId?: string;
+}
+export interface BigQueryExtractOptions {
+    format?: "CSV" | "NEWLINE_DELIMITED_JSON" | "AVRO" | "PARQUET";
+    gzip?: boolean;
+    labels?: Record<string, string>;
+}
+/** Structural subset of `@google-cloud/storage`'s File — only what a
+ *  destination for `Table#createExtractJob` needs to carry. */
+export interface GcsFileLike {
+    readonly name: string;
+    readonly bucket: {
+        readonly name: string;
+    };
+}
+export interface BigQueryTableLike {
+    createExtractJob(destination: GcsFileLike, options?: BigQueryExtractOptions): Promise<[BigQueryJobLike, BigQueryJobMetadata]>;
+}
+export interface BigQueryDatasetLike {
+    table(id: string): BigQueryTableLike;
+}
+export interface BigQueryLike {
+    createQueryJob(options: BigQueryCreateQueryJobOptions): Promise<[BigQueryJobLike, BigQueryJobMetadata]>;
+    dataset(id: string): BigQueryDatasetLike;
+    /** Looks up an already-submitted job by id — used to poll extract-job status
+     *  independently of the handle returned at submission time. */
+    job(id: string): BigQueryJobLike;
+}
+export interface RunQueryOptions {
+    /** The parameterised SQL. Always use `params`/`types` for user-supplied
+     *  values — never string-interpolate them into `sql`. */
+    sql: string;
+    params?: unknown[] | Record<string, unknown>;
+    types?: unknown[] | Record<string, string>;
+    labels?: Record<string, string>;
+    location?: string;
+    /** Page size. Omit to let BigQuery pick a default. */
+    pageSize?: number;
+    /** Resume a prior page — from `QueryPage.nextPageToken`. */
+    pageToken?: string;
+}
+export interface QueryPage<T = Record<string, unknown>> {
+    rows: T[];
+    jobId: string;
+    /** Present when another page is available. */
+    nextPageToken?: string;
+}
+export interface EstimateQueryBytesOptions {
+    sql: string;
+    params?: unknown[] | Record<string, unknown>;
+    types?: unknown[] | Record<string, string>;
+    location?: string;
+    /** When given, `estimateQueryBytes` throws `DryRunBudgetExceededError`
+     *  instead of returning once the estimate exceeds this many bytes. */
+    maxBytesBilled?: number;
+}
+export interface DryRunEstimate {
+    totalBytesProcessed: number;
+    cacheHit: boolean;
+}
+export interface ExtractTableToGCSInput {
+    datasetId: string;
+    tableId: string;
+    destination: GcsFileLike;
+    format?: BigQueryExtractOptions["format"];
+    gzip?: boolean;
+    labels?: Record<string, string>;
+}
+export interface ExtractJobHandle {
+    jobId: string;
+}
+export type ExtractJobState = "PENDING" | "RUNNING" | "DONE" | "UNKNOWN";
+export interface ExtractJobStatus {
+    jobId: string;
+    state: ExtractJobState;
+    done: boolean;
+    errors?: BigQueryApiErrorDetail[];
+}
+export interface WaitForExtractJobOptions {
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+}
+/** Who ran the query/extract, and for what — merged into every job's
+ *  `labels` so usage can be attributed after the fact in BigQuery's own job
+ *  history / billing export. */
+export interface JobLabelInput {
+    actor: string;
+    purpose: string;
+    extra?: Record<string, string>;
+}

package/dist/bigquery/types.js

@@ -0,0 +1,15 @@
+/**
+ * Structural (duck-typed) subset of `@google-cloud/bigquery`'s own BigQuery /
+ * Job / Dataset / Table classes that this module actually calls — mirrors
+ * src/trace/types.ts's TracePrismaClient boundary: deliberately NOT a
+ * dependency on `@google-cloud/bigquery` (this package has no hard dependency
+ * on any GCP SDK), so a real `new BigQuery()` instance satisfies BigQueryLike
+ * directly (TypeScript structural typing — its Job/Dataset/Table classes carry
+ * every member below), and a test fake can implement just this surface without
+ * mocking the SDK's own internals. AK-11: extracted from media-planner's
+ * `apps/api/src/services/inventoryWarehouse.ts`, generalizing the
+ * `@google-cloud/bigquery` calls it made; inventory-specific SQL stays behind
+ * in media-planner.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/bigquery/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/bigquery/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/chat/callback-secret.d.ts

@@ -0,0 +1,21 @@
+/**
+ * One constant-time shared-secret bearer guard for the dispatched agent's callback
+ * leg — extracted from media-planner's `apps/api/src/lib/callbackSecret.ts` (there,
+ * shared between the danxbot chat callback and an unrelated internal-task route). No
+ * behavior changed in the port: same compare, same preHandler contract.
+ */
+import type { FastifyReply, FastifyRequest } from "fastify";
+/**
+ * Constant-time compare of a presented secret against the expected one.
+ * `timingSafeEqual` throws on a length mismatch, so lengths are compared first —
+ * the one thing this deliberately leaks, which is fine: the length of a secret is
+ * not the secret. An empty expected secret can never match a non-empty (or equally
+ * empty) presented one, so an unconfigured environment fails closed.
+ */
+export declare function callbackSecretMatches(expected: string, presented: string): boolean;
+/**
+ * preHandler factory: requires `Authorization: Bearer <expectedSecret>`. These
+ * routes carry no user session — the caller is a service (the dispatched agent's MCP
+ * server) — so this shared secret is the only thing guarding them.
+ */
+export declare function requireCallbackSecret(expectedSecret: string): (request: FastifyRequest, reply: FastifyReply, done: () => void) => void;

package/dist/chat/callback-secret.js

@@ -0,0 +1,33 @@
+import { timingSafeEqual } from "node:crypto";
+const BEARER_PREFIX = "Bearer ";
+/**
+ * Constant-time compare of a presented secret against the expected one.
+ * `timingSafeEqual` throws on a length mismatch, so lengths are compared first —
+ * the one thing this deliberately leaks, which is fine: the length of a secret is
+ * not the secret. An empty expected secret can never match a non-empty (or equally
+ * empty) presented one, so an unconfigured environment fails closed.
+ */
+export function callbackSecretMatches(expected, presented) {
+    const e = Buffer.from(expected, "utf8");
+    const a = Buffer.from(presented, "utf8");
+    if (e.length === 0 || e.length !== a.length)
+        return false;
+    return timingSafeEqual(e, a);
+}
+/**
+ * preHandler factory: requires `Authorization: Bearer <expectedSecret>`. These
+ * routes carry no user session — the caller is a service (the dispatched agent's MCP
+ * server) — so this shared secret is the only thing guarding them.
+ */
+export function requireCallbackSecret(expectedSecret) {
+    return function callbackSecretPreHandler(request, reply, done) {
+        const header = request.headers.authorization;
+        if (!header?.startsWith(BEARER_PREFIX) ||
+            !callbackSecretMatches(expectedSecret, header.slice(BEARER_PREFIX.length))) {
+            reply.code(401).send({ error: "Invalid callback credentials", code: "unauthenticated" });
+            return;
+        }
+        done();
+    };
+}
+//# sourceMappingURL=callback-secret.js.map

package/dist/chat/callback-secret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback-secret.js","sourceRoot":"","sources":["../../src/chat/callback-secret.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,aAAa,GAAG,SAAS,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB,EAAE,SAAiB;IACvE,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IACzC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1D,OAAO,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,cAAsB;IAEtB,OAAO,SAAS,wBAAwB,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI;QAC3D,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC;QAC7C,IACE,CAAC,MAAM,EAAE,UAAU,CAAC,aAAa,CAAC;YAClC,CAAC,qBAAqB,CAAC,cAAc,EAAE,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,EAC1E,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,8BAA8B,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC,CAAC;YACzF,OAAO;QACT,CAAC;QACD,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC"}

package/dist/chat/env.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The env contract every app wiring @flytedesk/app-kit/chat shares — extracted from
+ * media-planner's `apps/api/src/env.ts` (the `DANXBOT_*` slice of it, lines 35-66).
+ * Merge these keys into your app's own env schema/parsing; this module only owns
+ * their names and defaults, not how the rest of your app reads env.
+ */
+import type { ChatEnv } from "./types.js";
+export declare class ChatEnvError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse the `DANXBOT_*` chat env vars out of a process-env-shaped source.
+ *
+ * `DANXBOT_API_TOKEN` and `DANXBOT_CALLBACK_SECRET` default to `""` ON PURPOSE — an
+ * empty value is a valid state (danxbot isn't configured for this environment yet,
+ * e.g. production before rollout), and every call site (the launcher's DanxbotError
+ * path, `requireCallbackSecret`'s fail-closed compare) already turns a rejected or
+ * failed request into a normal error rather than crashing. Requiring either at boot
+ * would crash the entire consuming app in any environment without a real danxbot
+ * deployment, not just degrade the chat feature.
+ *
+ * `DANXBOT_BOARD_ID` and `DANXBOT_CALLBACK_API_URL` have no universal default —
+ * each is inherently per-app (which board a chat turn dispatches onto; the URL the
+ * dispatched agent's MCP server can reach this app's callback routes through, e.g.
+ * `host.docker.internal:<port>` for a local worker) — so both are required.
+ */
+export declare function parseChatEnv(source: Record<string, string | undefined>): ChatEnv;

package/dist/chat/env.js

@@ -0,0 +1,44 @@
+export class ChatEnvError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ChatEnvError";
+    }
+}
+/**
+ * Parse the `DANXBOT_*` chat env vars out of a process-env-shaped source.
+ *
+ * `DANXBOT_API_TOKEN` and `DANXBOT_CALLBACK_SECRET` default to `""` ON PURPOSE — an
+ * empty value is a valid state (danxbot isn't configured for this environment yet,
+ * e.g. production before rollout), and every call site (the launcher's DanxbotError
+ * path, `requireCallbackSecret`'s fail-closed compare) already turns a rejected or
+ * failed request into a normal error rather than crashing. Requiring either at boot
+ * would crash the entire consuming app in any environment without a real danxbot
+ * deployment, not just degrade the chat feature.
+ *
+ * `DANXBOT_BOARD_ID` and `DANXBOT_CALLBACK_API_URL` have no universal default —
+ * each is inherently per-app (which board a chat turn dispatches onto; the URL the
+ * dispatched agent's MCP server can reach this app's callback routes through, e.g.
+ * `host.docker.internal:<port>` for a local worker) — so both are required.
+ */
+export function parseChatEnv(source) {
+    const boardId = source.DANXBOT_BOARD_ID;
+    if (!boardId) {
+        throw new ChatEnvError("DANXBOT_BOARD_ID is required (the danxbot board this app dispatches chat turns onto)");
+    }
+    const callbackApiUrl = source.DANXBOT_CALLBACK_API_URL;
+    if (!callbackApiUrl) {
+        throw new ChatEnvError("DANXBOT_CALLBACK_API_URL is required (the URL the dispatched agent's MCP server reaches this app through)");
+    }
+    return {
+        // Deliberately `||`, not `??`, unlike the token/secret below: an empty string is
+        // never a valid URL (unlike an empty token/secret, which is a real "not
+        // configured yet" sentinel — see their own comments), so an explicitly empty
+        // DANXBOT_API_URL should fall back to the default exactly like an unset one.
+        danxbotApiUrl: source.DANXBOT_API_URL || "http://localhost:5555",
+        danxbotBoardId: boardId,
+        danxbotApiToken: source.DANXBOT_API_TOKEN ?? "",
+        danxbotCallbackApiUrl: callbackApiUrl,
+        danxbotCallbackSecret: source.DANXBOT_CALLBACK_SECRET ?? "",
+    };
+}
+//# sourceMappingURL=env.js.map

package/dist/chat/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/chat/env.ts"],"names":[],"mappings":"AAQA,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAAC,MAA0C;IACrE,MAAM,OAAO,GAAG,MAAM,CAAC,gBAAgB,CAAC;IACxC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,YAAY,CAAC,sFAAsF,CAAC,CAAC;IACjH,CAAC;IACD,MAAM,cAAc,GAAG,MAAM,CAAC,wBAAwB,CAAC;IACvD,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,MAAM,IAAI,YAAY,CACpB,2GAA2G,CAC5G,CAAC;IACJ,CAAC;IACD,OAAO;QACL,iFAAiF;QACjF,wEAAwE;QACxE,6EAA6E;QAC7E,6EAA6E;QAC7E,aAAa,EAAE,MAAM,CAAC,eAAe,IAAI,uBAAuB;QAChE,cAAc,EAAE,OAAO;QACvB,eAAe,EAAE,MAAM,CAAC,iBAAiB,IAAI,EAAE;QAC/C,qBAAqB,EAAE,cAAc;QACrC,qBAAqB,EAAE,MAAM,CAAC,uBAAuB,IAAI,EAAE;KAC5D,CAAC;AACJ,CAAC"}

package/dist/chat/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The danxbot agent-chat bridge — DEC-51 (AK-12). Extracted and generalized from
+ * media-planner's in-app assistant (`apps/api/src/lib/danxbot.ts` + `services/
+ * chat.ts` + `routes/chat.ts` + `packages/chat-mcp`), so any flytedesk app can give
+ * its own chat sidebar a real danxbot agent without re-solving dispatch launch, the
+ * reply protocol, or the callback secret from scratch.
+ *
+ * Four pieces, usable independently or together:
+ *
+ *  - `createDanxbotLauncher` — dispatch (and resume) a danxbot chat turn.
+ *  - `createChatMcpProtocol` + `createReplyTool` — the MCP server the dispatched
+ *    agent talks to the user through, with an extension point for app-registered
+ *    tools (see AppRegisteredTool).
+ *  - `createChatMcpStdioServer` — the newline-delimited JSON-RPC stdio transport for
+ *    the above, built on Node builtins only (no runtime dependency) so it can run
+ *    from an unbuilt clone the way danxbot's dispatched agents expect.
+ *  - `callbackSecretMatches` / `requireCallbackSecret` — the constant-time guard for
+ *    the HTTP routes the dispatched agent's MCP server calls back into.
+ *  - `parseChatEnv` — the `DANXBOT_*` env var contract all of the above share.
+ *
+ * Usage — the app's own Fastify API process (launch + callback routes):
+ *
+ *   import { createDanxbotLauncher, requireCallbackSecret, parseChatEnv } from "@flytedesk/app-kit/chat";
+ *
+ *   const chatEnv = parseChatEnv(process.env);
+ *   const launcher = createDanxbotLauncher({
+ *     apiUrl: chatEnv.danxbotApiUrl,
+ *     apiToken: chatEnv.danxbotApiToken,
+ *     board: chatEnv.danxbotBoardId,
+ *     profile: "board-chat",
+ *   });
+ *
+ *   const { jobId } = await launcher.dispatchChatTurn({
+ *     task: prompt,
+ *     overlay: { TURN_ID: turn.id, API_URL: chatEnv.danxbotCallbackApiUrl, CALLBACK_SECRET: chatEnv.danxbotCallbackSecret },
+ *   });
+ *
+ *   fastify.post(
+ *     "/chat/internal/reply",
+ *     { preHandler: requireCallbackSecret(chatEnv.danxbotCallbackSecret) },
+ *     async (request) => recordReply(request.body),
+ *   );
+ *
+ * Usage — the MCP server script the dispatched agent's clean room actually runs
+ * (typically `dist/chat/mcp/entry.js`, wired through a `.danxbot/config/mcp-servers/
+ * *.yml`):
+ *
+ *   import {
+ *     createChatMcpProtocol,
+ *     createChatMcpStdioServer,
+ *     createReplyTool,
+ *   } from "@flytedesk/app-kit/chat";
+ *
+ *   const protocol = createChatMcpProtocol({
+ *     serverName: "sms-app-chat",
+ *     tools: [
+ *       createReplyTool({ description: "...", deliver: postReplyToApi }),
+ *       // The extension point: register whatever app-specific tools the agent
+ *       // needs — each is just { name, description, inputSchema, handler }.
+ *       { name: "audience_validate", description: "...", inputSchema: {...}, handler: validateAudience },
+ *     ],
+ *   });
+ *   createChatMcpStdioServer({ protocol }).start();
+ */
+export { createDanxbotLauncher, DanxbotError, isFailedJobStatus, isTerminalJobStatus } from "./launcher.js";
+export { callbackSecretMatches, requireCallbackSecret } from "./callback-secret.js";
+export { createChatMcpProtocol, createReplyTool, parseReplyArguments, FALLBACK_PROTOCOL_VERSION, JSON_RPC, } from "./mcp-protocol.js";
+export { createChatMcpStdioServer } from "./mcp-server.js";
+export { parseChatEnv, ChatEnvError } from "./env.js";
+export type { AppRegisteredTool, ChatEnv, ChatToolCallResult, ChatToolContent, DanxbotDispatchResult, DanxbotJobStatus, DanxbotLauncher, DanxbotLauncherOptions, } from "./types.js";
+export type { ChatMcpProtocol, ChatMcpProtocolOptions, ChatReplyPayload, ParseReplyArgumentsOptions, ReplyDeliverResult, ReplyToolOptions, } from "./mcp-protocol.js";
+export type { ChatMcpStdioServer, ChatMcpStdioServerOptions } from "./mcp-server.js";

package/dist/chat/index.js

@@ -0,0 +1,70 @@
+/**
+ * The danxbot agent-chat bridge — DEC-51 (AK-12). Extracted and generalized from
+ * media-planner's in-app assistant (`apps/api/src/lib/danxbot.ts` + `services/
+ * chat.ts` + `routes/chat.ts` + `packages/chat-mcp`), so any flytedesk app can give
+ * its own chat sidebar a real danxbot agent without re-solving dispatch launch, the
+ * reply protocol, or the callback secret from scratch.
+ *
+ * Four pieces, usable independently or together:
+ *
+ *  - `createDanxbotLauncher` — dispatch (and resume) a danxbot chat turn.
+ *  - `createChatMcpProtocol` + `createReplyTool` — the MCP server the dispatched
+ *    agent talks to the user through, with an extension point for app-registered
+ *    tools (see AppRegisteredTool).
+ *  - `createChatMcpStdioServer` — the newline-delimited JSON-RPC stdio transport for
+ *    the above, built on Node builtins only (no runtime dependency) so it can run
+ *    from an unbuilt clone the way danxbot's dispatched agents expect.
+ *  - `callbackSecretMatches` / `requireCallbackSecret` — the constant-time guard for
+ *    the HTTP routes the dispatched agent's MCP server calls back into.
+ *  - `parseChatEnv` — the `DANXBOT_*` env var contract all of the above share.
+ *
+ * Usage — the app's own Fastify API process (launch + callback routes):
+ *
+ *   import { createDanxbotLauncher, requireCallbackSecret, parseChatEnv } from "@flytedesk/app-kit/chat";
+ *
+ *   const chatEnv = parseChatEnv(process.env);
+ *   const launcher = createDanxbotLauncher({
+ *     apiUrl: chatEnv.danxbotApiUrl,
+ *     apiToken: chatEnv.danxbotApiToken,
+ *     board: chatEnv.danxbotBoardId,
+ *     profile: "board-chat",
+ *   });
+ *
+ *   const { jobId } = await launcher.dispatchChatTurn({
+ *     task: prompt,
+ *     overlay: { TURN_ID: turn.id, API_URL: chatEnv.danxbotCallbackApiUrl, CALLBACK_SECRET: chatEnv.danxbotCallbackSecret },
+ *   });
+ *
+ *   fastify.post(
+ *     "/chat/internal/reply",
+ *     { preHandler: requireCallbackSecret(chatEnv.danxbotCallbackSecret) },
+ *     async (request) => recordReply(request.body),
+ *   );
+ *
+ * Usage — the MCP server script the dispatched agent's clean room actually runs
+ * (typically `dist/chat/mcp/entry.js`, wired through a `.danxbot/config/mcp-servers/
+ * *.yml`):
+ *
+ *   import {
+ *     createChatMcpProtocol,
+ *     createChatMcpStdioServer,
+ *     createReplyTool,
+ *   } from "@flytedesk/app-kit/chat";
+ *
+ *   const protocol = createChatMcpProtocol({
+ *     serverName: "sms-app-chat",
+ *     tools: [
+ *       createReplyTool({ description: "...", deliver: postReplyToApi }),
+ *       // The extension point: register whatever app-specific tools the agent
+ *       // needs — each is just { name, description, inputSchema, handler }.
+ *       { name: "audience_validate", description: "...", inputSchema: {...}, handler: validateAudience },
+ *     ],
+ *   });
+ *   createChatMcpStdioServer({ protocol }).start();
+ */
+export { createDanxbotLauncher, DanxbotError, isFailedJobStatus, isTerminalJobStatus } from "./launcher.js";
+export { callbackSecretMatches, requireCallbackSecret } from "./callback-secret.js";
+export { createChatMcpProtocol, createReplyTool, parseReplyArguments, FALLBACK_PROTOCOL_VERSION, JSON_RPC, } from "./mcp-protocol.js";
+export { createChatMcpStdioServer } from "./mcp-server.js";
+export { parseChatEnv, ChatEnvError } from "./env.js";
+//# sourceMappingURL=index.js.map

package/dist/chat/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/chat/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC5G,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,yBAAyB,EACzB,QAAQ,GACT,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC"}

package/dist/chat/launcher.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A danxbot dispatch client for a per-turn chat bridge — the ONLY place a consuming
+ * app should speak danxbot's `/api/launch` / `/api/resume` / `/api/status` contract.
+ *
+ * Extracted from media-planner's `apps/api/src/lib/danxbot.ts`, generalized so
+ * `board`/`profile` are options instead of one app's hardcoded values. The wire
+ * contract itself did not change:
+ *
+ *   POST /api/launch  {board, profile, task, overlay?}
+ *     -> 200 {"job_id":"e4d603a3-…","status":"launched"}
+ *   POST /api/resume  {board, profile, task, job_id, overlay?}
+ *     -> 200 {"job_id":"2aaac2e1-…","parent_job_id":"e4d603a3-…","status":"launched"}
+ *   GET  /api/status/:jobId
+ *     -> 200 {"job_id":…,"status":"running"|"completed"|…,"summary":…,"elapsed_seconds":…,
+ *             "input_tokens":…,"output_tokens":…,"cache_read_input_tokens":…,
+ *             "cache_creation_input_tokens":…}
+ *
+ * `resume` is what makes a thread a thread: passing the previous turn's `job_id`
+ * resumes the underlying Claude session (`claude --resume`), so a later turn
+ * remembers an earlier one. `overlay` is danxbot's per-dispatch substitution map:
+ * its values are substituted into the dispatched agent's clean-room MCP-server env
+ * — see mcp-protocol.ts / mcp-server.ts for the reply side of that channel.
+ */
+import type { DanxbotLauncher, DanxbotLauncherOptions } from "./types.js";
+/**
+ * danxbot rejected the call. Carries the HTTP status so a caller can tell a
+ * misconfiguration (4xx — bad board, unknown profile, revoked token) apart from a
+ * worker that is down or wedged (5xx / network), which are different operator
+ * problems even though both surface to the user as "the assistant is unavailable".
+ */
+export declare class DanxbotError extends Error {
+    readonly httpStatus: number | null;
+    constructor(message: string, httpStatus: number | null);
+}
+/**
+ * Create a launcher bound to one board/profile pair. One instance per consumer app
+ * (or per board, for an app dispatching onto more than one) — cheap, holds no
+ * mutable state of its own.
+ */
+export declare function createDanxbotLauncher(options: DanxbotLauncherOptions): DanxbotLauncher;
+export declare function isTerminalJobStatus(status: string): boolean;
+/** A terminal status that is terminal because something went WRONG. */
+export declare function isFailedJobStatus(status: string): boolean;

package/dist/chat/launcher.js

@@ -0,0 +1,103 @@
+/**
+ * danxbot rejected the call. Carries the HTTP status so a caller can tell a
+ * misconfiguration (4xx — bad board, unknown profile, revoked token) apart from a
+ * worker that is down or wedged (5xx / network), which are different operator
+ * problems even though both surface to the user as "the assistant is unavailable".
+ */
+export class DanxbotError extends Error {
+    httpStatus;
+    constructor(message, httpStatus) {
+        super(message);
+        this.httpStatus = httpStatus;
+        this.name = "DanxbotError";
+    }
+}
+async function danxbotFetch(options, path, init) {
+    let response;
+    try {
+        response = await fetch(`${options.apiUrl}${path}`, {
+            method: init.method,
+            headers: {
+                Authorization: `Bearer ${options.apiToken}`,
+                ...(init.body !== undefined ? { "Content-Type": "application/json" } : {}),
+            },
+            body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
+        });
+    }
+    catch (cause) {
+        // The worker is unreachable. Deliberately NOT swallowed into a placeholder
+        // result: a chat that silently never answers is worse than one that says it is
+        // down.
+        throw new DanxbotError(`danxbot at ${options.apiUrl} is unreachable: ${cause.message}`, null);
+    }
+    const text = await response.text();
+    if (!response.ok) {
+        throw new DanxbotError(`danxbot ${init.method} ${path} returned ${response.status}: ${text}`, response.status);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new DanxbotError(`danxbot ${init.method} ${path} returned unparseable body: ${text}`, response.status);
+    }
+}
+/**
+ * Create a launcher bound to one board/profile pair. One instance per consumer app
+ * (or per board, for an app dispatching onto more than one) — cheap, holds no
+ * mutable state of its own.
+ */
+export function createDanxbotLauncher(options) {
+    return {
+        /**
+         * Dispatch a chat turn. `parentJobId` selects the endpoint: absent starts a
+         * fresh Claude session (`/api/launch`), present continues the one that job
+         * belongs to (`/api/resume`). Both carry the same `board`/`profile`/`task`/
+         * `overlay` shape — the only difference on the wire is the extra `job_id`.
+         */
+        async dispatchChatTurn(input) {
+            const body = {
+                board: options.board,
+                profile: options.profile,
+                task: input.task,
+                overlay: input.overlay,
+                ...(input.parentJobId ? { job_id: input.parentJobId } : {}),
+            };
+            const result = await danxbotFetch(options, input.parentJobId ? "/api/resume" : "/api/launch", { method: "POST", body });
+            return { jobId: result.job_id, parentJobId: result.parent_job_id };
+        },
+        async getJobStatus(jobId) {
+            const result = await danxbotFetch(options, `/api/status/${encodeURIComponent(jobId)}`, { method: "GET" });
+            return {
+                jobId: result.job_id,
+                status: result.status,
+                summary: result.summary ?? "",
+                elapsedSeconds: result.elapsed_seconds ?? 0,
+                inputTokens: result.input_tokens ?? 0,
+                outputTokens: result.output_tokens ?? 0,
+                cacheReadInputTokens: result.cache_read_input_tokens ?? 0,
+                cacheCreationInputTokens: result.cache_creation_input_tokens ?? 0,
+            };
+        },
+    };
+}
+/**
+ * danxbot job statuses that mean "this job will never produce anything more".
+ * Anything else (including an unknown one — danxbot owns this vocabulary and may
+ * grow it) is treated as still in flight, so a status danxbot adds later can never
+ * make a consumer declare a live turn dead.
+ */
+const TERMINAL_JOB_STATUSES = new Set([
+    "completed",
+    "failed",
+    "critical_failure",
+    "cancelled",
+    "aborted",
+]);
+export function isTerminalJobStatus(status) {
+    return TERMINAL_JOB_STATUSES.has(status);
+}
+/** A terminal status that is terminal because something went WRONG. */
+export function isFailedJobStatus(status) {
+    return isTerminalJobStatus(status) && status !== "completed";
+}
+//# sourceMappingURL=launcher.js.map

package/dist/chat/launcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launcher.js","sourceRoot":"","sources":["../../src/chat/launcher.ts"],"names":[],"mappings":"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"}