@flytedesk/app-kit 4.0.0 → 6.0.0

package/dist/bigquery/load.js

@@ -1,61 +1,91 @@
 /**
- * Load-job capability (AK-14 follow-on, MP-200/PLN-2): truncate-and-reload a
- * BigQuery table from an array of rows, with retry-with-backoff limited to
+ * Load-job capability (AK-14 follow-on, MP-200/PLN-2): loads a stream of rows
+ * into a BigQuery table in one load job, with retry-with-backoff limited to
  * BigQuery's own rate-limit/quota class of error — generalized out of
  * media-planner's `apps/api/src/lib/bigqueryLoad.ts` (via flytedesk-id's
  * verbatim port at `src/lib/bigqueryLoad.ts`, MP-200), which this module
- * replaces. Callers needing a periodic full-refresh load (e.g. the IPEDS
- * institutions loader) use this instead of keeping their own copy of the
- * write-stream + retry plumbing.
+ * replaces.
+ *
+ * Memory is bounded by `chunkBytes`, never by the row count (AK-28): rows are
+ * pulled from the caller's source one at a time, serialized into NDJSON chunks
+ * of about `chunkBytes`, and piped into the load job's write stream with
+ * `stream.pipeline`, which stops pulling from the source whenever the write
+ * stream's buffer is full and resumes on its `drain`. A caller that reads its
+ * rows page by page (a keyset-paged or cursor read) can therefore load any
+ * number of rows in a fixed amount of memory.
  */
-import { BigQueryReadError, classifyBigQueryError, isRetryableBigQueryError } from "./errors.js";
+import { once } from "node:events";
+import { pipeline } from "node:stream/promises";
+import { BigQueryReadError, classifyBigQueryError, isRetryableBigQueryError, } from "./errors.js";
 const DEFAULT_ATTEMPTS = 5;
 const DEFAULT_INITIAL_DELAY_MS = 1_000;
+const DEFAULT_CHUNK_BYTES = 1024 * 1024;
 const DEFAULT_SOURCE_FORMAT = "NEWLINE_DELIMITED_JSON";
 function defaultSleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-async function runLoadJob(bq, options, rows) {
+/** Serializes `rows` into NDJSON, one `Buffer` of about `chunkBytes` at a
+ *  time, counting rows into `counter` as they are consumed. */
+async function* ndjsonChunks(rows, chunkBytes, counter) {
+    let lines = [];
+    let size = 0;
+    for await (const row of rows) {
+        const line = `${JSON.stringify(row)}\n`;
+        lines.push(line);
+        size += Buffer.byteLength(line);
+        counter.rows += 1;
+        if (size >= chunkBytes) {
+            yield Buffer.from(lines.join(""));
+            lines = [];
+            size = 0;
+        }
+    }
+    if (lines.length > 0)
+        yield Buffer.from(lines.join(""));
+}
+async function runLoadJob(bq, options, source) {
     const table = bq.dataset(options.datasetId).table(options.tableId);
     const createWriteStream = table.createWriteStream;
     if (!createWriteStream) {
         throw new BigQueryReadError(`dataset(${options.datasetId}).table(${options.tableId}) does not implement createWriteStream — this BigQueryLike was not constructed for load jobs`);
     }
-    const ndjson = rows.map((row) => `${JSON.stringify(row)}\n`);
-    await new Promise((resolve, reject) => {
-        const stream = createWriteStream.call(table, {
-            sourceFormat: options.sourceFormat ?? DEFAULT_SOURCE_FORMAT,
-            schema: options.schema,
-            writeDisposition: options.writeDisposition,
-            createDisposition: options.createDisposition,
-            labels: options.labels,
-            jobId: options.jobId,
-        });
-        stream.on("error", reject);
-        stream.on("complete", () => resolve());
-        for (const line of ndjson)
-            stream.write(line);
-        stream.end();
+    const stream = createWriteStream.call(table, {
+        sourceFormat: options.sourceFormat ?? DEFAULT_SOURCE_FORMAT,
+        schema: options.schema,
+        writeDisposition: options.writeDisposition,
+        createDisposition: options.createDisposition,
+        labels: options.labels,
+        jobId: options.jobId,
     });
+    const counter = { rows: 0 };
+    // The load is done only when BigQuery reports the job "complete" AND the
+    // pipeline has flushed every chunk. `once` rejects on the stream's "error",
+    // which is how a failed job surfaces; `pipeline` rejects (and destroys the
+    // stream, aborting the upload) when the source itself throws.
+    await Promise.all([
+        once(stream, "complete"),
+        pipeline(ndjsonChunks(source(), options.chunkBytes ?? DEFAULT_CHUNK_BYTES, counter), stream),
+    ]);
+    return { rowCount: counter.rows };
 }
 /**
- * Loads `rows` into `datasetId.tableId` in one load job, retrying with
- * exponential backoff ONLY when the failure is BigQuery's
+ * Streams the rows `source` yields into `datasetId.tableId` in one load job,
+ * retrying with exponential backoff ONLY when the failure is BigQuery's
  * rateLimitExceeded/quotaExceeded class of error (see
- * `isRetryableBigQueryError`). Any other error (bad schema, auth failure,
- * etc.) is classified and rethrown on the first attempt.
+ * `isRetryableBigQueryError`). Any other error (bad schema, auth failure, a
+ * throw from the source, etc.) is classified and rethrown on the first
+ * attempt. Each attempt calls `source` afresh — see `LoadRowSource`.
  *
- * Pass `writeDisposition: "WRITE_TRUNCATE"` for a full-refresh reload (the
- * IPEDS institutions loader's use case); omit it for an append load.
+ * Pass `writeDisposition: "WRITE_TRUNCATE"` for a full-refresh reload; omit it
+ * for an append load.
  */
-export async function loadRowsWithRetry(bq, options, rows) {
+export async function loadRowsWithRetry(bq, options, source) {
     const attempts = options.attempts ?? DEFAULT_ATTEMPTS;
     const initialDelayMs = options.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS;
     const sleep = options.sleep ?? defaultSleep;
     for (let attempt = 1;; attempt += 1) {
         try {
-            await runLoadJob(bq, options, rows);
-            return;
+            return await runLoadJob(bq, options, source);
         }
         catch (err) {
             if (attempt >= attempts || !isRetryableBigQueryError(err)) {

package/dist/bigquery/load.js.map

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

package/dist/bigquery/query.js

@@ -4,8 +4,9 @@
  * (AK-11). Inventory-specific SQL stays in media-planner; this module only
  * ever takes SQL + params from the caller and runs it.
  */
-import { BadQueryError, classifyBigQueryError } from "./errors.js";
+import { BadQueryError, classifyBigQueryError, isJobTimeoutError, JobTimeoutError } from "./errors.js";
 import { DryRunBudgetExceededError } from "./errors.js";
+import { normalizeResultSchema } from "./schema.js";
 /** Runs one page of a parameterised, read-only query. Always bind
  *  user-supplied values through `options.params`/`options.types` — never
  *  string-interpolate them into `options.sql`.
@@ -34,9 +35,13 @@ export async function runQuery(bq, options) {
                 maximumBytesBilled: options.maximumBytesBilled !== undefined
                     ? String(options.maximumBytesBilled)
                     : undefined,
+                jobTimeoutMs: options.jobTimeoutMs,
             });
         }
         catch (err) {
+            if (options.jobTimeoutMs !== undefined && isJobTimeoutError(err)) {
+                throw new JobTimeoutError(options.jobTimeoutMs, err);
+            }
             throw classifyBigQueryError(err);
         }
     }
@@ -52,6 +57,9 @@ export async function runQuery(bq, options) {
         };
     }
     catch (err) {
+        if (options.jobTimeoutMs !== undefined && isJobTimeoutError(err)) {
+            throw new JobTimeoutError(options.jobTimeoutMs, err);
+        }
         throw classifyBigQueryError(err);
     }
 }
@@ -87,9 +95,13 @@ export async function estimateQueryBytes(bq, options) {
             types: options.types,
             location: options.location,
             dryRun: true,
+            jobTimeoutMs: options.jobTimeoutMs,
         });
     }
     catch (err) {
+        if (options.jobTimeoutMs !== undefined && isJobTimeoutError(err)) {
+            throw new JobTimeoutError(options.jobTimeoutMs, err);
+        }
         throw classifyBigQueryError(err);
     }
     const stats = metadata.statistics?.query;
@@ -98,6 +110,7 @@ export async function estimateQueryBytes(bq, options) {
         cacheHit: stats?.cacheHit ?? false,
         statementType: stats?.statementType,
         referencedTables: stats?.referencedTables,
+        schema: normalizeResultSchema(stats?.schema),
     };
     if (options.maxBytesBilled !== undefined &&
         estimate.totalBytesProcessed > options.maxBytesBilled) {

package/dist/bigquery/query.js.map

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

package/dist/bigquery/schema.d.ts

@@ -0,0 +1,5 @@
+import type { BigQueryRawSchema, BigQueryResultSchemaField } from "./types.js";
+/** `undefined` when BigQuery sent no schema at all; `[]` when it sent one with
+ *  no fields. Throws `MalformedResultSchemaError` for a field lacking a
+ *  non-empty `name` or `type`, at any nesting depth. */
+export declare function normalizeResultSchema(schema: BigQueryRawSchema | undefined): BigQueryResultSchemaField[] | undefined;

package/dist/bigquery/schema.js

@@ -0,0 +1,35 @@
+/**
+ * Parses BigQuery's raw dry-run result schema (every property optional, as the
+ * real SDK types it) into the normalised `BigQueryResultSchemaField[]` callers
+ * get. Parse at the boundary: a field missing `name` or `type` is a typed error
+ * here rather than a silent `undefined` downstream (AK-31).
+ */
+import { MalformedResultSchemaError } from "./errors.js";
+/** `undefined` when BigQuery sent no schema at all; `[]` when it sent one with
+ *  no fields. Throws `MalformedResultSchemaError` for a field lacking a
+ *  non-empty `name` or `type`, at any nesting depth. */
+export function normalizeResultSchema(schema) {
+    if (schema === undefined)
+        return undefined;
+    return normalizeFields(schema.fields ?? [], "");
+}
+function normalizeFields(fields, parentPath) {
+    return fields.map((field, index) => normalizeField(field, index, parentPath));
+}
+function normalizeField(field, index, parentPath) {
+    const { name, type } = field;
+    if (!name) {
+        throw new MalformedResultSchemaError(`${parentPath}fields[${index}]`, "name");
+    }
+    const path = `${parentPath}${name}`;
+    if (!type) {
+        throw new MalformedResultSchemaError(path, "type");
+    }
+    const normalized = { name, type };
+    if (field.mode !== undefined)
+        normalized.mode = field.mode;
+    if (field.fields !== undefined)
+        normalized.fields = normalizeFields(field.fields, `${path}.`);
+    return normalized;
+}
+//# sourceMappingURL=schema.js.map

package/dist/bigquery/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/bigquery/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAOzD;;wDAEwD;AACxD,MAAM,UAAU,qBAAqB,CACnC,MAAqC;IAErC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC3C,OAAO,eAAe,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,eAAe,CACtB,MAAgC,EAChC,UAAkB;IAElB,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC;AAChF,CAAC;AAED,SAAS,cAAc,CACrB,KAA6B,EAC7B,KAAa,EACb,UAAkB;IAElB,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IAC7B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,0BAA0B,CAAC,GAAG,UAAU,UAAU,KAAK,GAAG,EAAE,MAAM,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,UAAU,GAAG,IAAI,EAAE,CAAC;IACpC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,0BAA0B,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrD,CAAC;IACD,MAAM,UAAU,GAA8B,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC7D,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,UAAU,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IAC3D,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,UAAU,CAAC,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,CAAC;IAC9F,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/bigquery/types.d.ts

@@ -11,6 +11,7 @@
  * `@google-cloud/bigquery` calls it made; inventory-specific SQL stays behind
  * in media-planner.
  */
+import type { Writable } from "node:stream";
 /** One structured error entry, same shape the Google APIs client library
  *  attaches to a rejected job promise's `.errors` array. */
 export interface BigQueryApiErrorDetail {
@@ -31,6 +32,20 @@ export interface BigQueryTableReference {
     datasetId?: string;
     tableId?: string;
 }
+/** A result-schema field exactly as BigQuery's job statistics report it: the
+ *  real SDK's `ITableFieldSchema`, where every property is optional. Only the
+ *  raw boundary speaks this shape; callers get `BigQueryResultSchemaField`
+ *  (name and type guaranteed) from `estimateQueryBytes`. */
+export interface BigQueryRawSchemaField {
+    name?: string;
+    type?: string;
+    mode?: string;
+    fields?: BigQueryRawSchemaField[];
+}
+/** `IJobStatistics2.schema`, an `ITableSchema`. */
+export interface BigQueryRawSchema {
+    fields?: BigQueryRawSchemaField[];
+}
 export interface BigQueryJobStatistics {
     query?: {
         totalBytesProcessed?: string | number;
@@ -41,6 +56,9 @@ export interface BigQueryJobStatistics {
         statementType?: string;
         /** Every table the query touches — `IJobStatistics2.referencedTables`. */
         referencedTables?: BigQueryTableReference[];
+        /** The result schema BigQuery computed for the (dry-run) query —
+         *  `IJobStatistics2.schema`, an `ITableSchema` (`{ fields }`). */
+        schema?: BigQueryRawSchema;
     };
 }
 export interface BigQueryJobMetadata {
@@ -91,6 +109,10 @@ export interface BigQueryCreateQueryJobOptions {
      *  than run. Distinct from `EstimateQueryBytesOptions.maxBytesBilled`
      *  (a pre-flight dry-run check this module enforces client-side). */
     maximumBytesBilled?: string;
+    /** BigQuery's own `configuration.jobTimeoutMs` — the job fails with
+     *  `stopped` state once it runs longer than this, wall-clock, from job
+     *  creation. The SDK converts this number to the wire's decimal string. */
+    jobTimeoutMs?: number;
 }
 export interface BigQueryExtractOptions {
     /** `@google-cloud/bigquery`'s own extract-job vocabulary — note this is
@@ -109,24 +131,26 @@ export interface GcsFileLike {
         readonly name: string;
     };
 }
-/** Structural subset of Node's own Writable that `Table#createWriteStream`
- *  needs to expose — the "error"/"complete" events a load-job caller pipes
- *  rows into and waits on. */
-export interface BigQueryWriteStreamLike {
-    on(event: "error", listener: (err: unknown) => void): this;
-    on(event: "complete", listener: () => void): this;
-    write(chunk: string): boolean;
-    end(): void;
-}
 /** One BigQuery table-schema field, as `createWriteStream`'s `schema` option
- *  (and the REST API's `tables.insert`) accepts it. `fields` recurses for
- *  RECORD/STRUCT columns. */
+ *  (and the REST API's `tables.insert`) accepts it: load-job INPUT, where the
+ *  caller must state `name` and `type`. `fields` recurses for RECORD/STRUCT
+ *  columns. The schema BigQuery reports back is `BigQueryResultSchemaField`. */
 export interface BigQuerySchemaField {
     name: string;
     type: string;
     mode?: "NULLABLE" | "REQUIRED" | "REPEATED";
     fields?: BigQuerySchemaField[];
 }
+/** One column of a query's result schema, normalised from BigQuery's own
+ *  dry-run statistics: `name` and `type` are guaranteed (a field missing
+ *  either is rejected with `MalformedResultSchemaError`); `mode` is BigQuery's
+ *  string as reported. `fields` recurses for RECORD/STRUCT columns. */
+export interface BigQueryResultSchemaField {
+    name: string;
+    type: string;
+    mode?: string;
+    fields?: BigQueryResultSchemaField[];
+}
 export interface BigQueryLoadOptions {
     sourceFormat?: "NEWLINE_DELIMITED_JSON" | "CSV" | "AVRO" | "PARQUET";
     /** Full destination-table schema. Required when the table doesn't already
@@ -143,12 +167,15 @@ export interface BigQueryLoadOptions {
 }
 export interface BigQueryTableLike {
     createExtractJob(destination: GcsFileLike, options?: BigQueryExtractOptions): Promise<[BigQueryJobLike, BigQueryJobMetadata]>;
-    /** Opens a load-job write stream — the caller pipes newline-delimited rows
-     *  (or other `sourceFormat`) into it, then awaits the stream's "complete"/
-     *  "error" event. Mirrors `@google-cloud/bigquery`'s `Table#createWriteStream`.
-     *  Optional: read-only callers (query/extract) never need it — only
-     *  `loadRowsWithRetry` (./load.js) does, and it fails loudly if missing. */
-    createWriteStream?(options: BigQueryLoadOptions): BigQueryWriteStreamLike;
+    /** Opens a load-job write stream — a real Node `Writable`, since the loader
+     *  pipes NDJSON into it with `stream.pipeline` and relies on its
+     *  backpressure (`write()` returning false, then "drain"). The stream emits
+     *  "complete" once BigQuery finishes the job, or "error" if the job fails.
+     *  Mirrors `@google-cloud/bigquery`'s `Table#createWriteStream`, which
+     *  returns a `Writable`. Optional: read-only callers (query/extract) never
+     *  need it — only `loadRowsWithRetry` (./load.js) does, and it fails loudly
+     *  if missing. */
+    createWriteStream?(options: BigQueryLoadOptions): Writable;
 }
 export interface BigQueryDatasetLike {
     table(id: string): BigQueryTableLike;
@@ -187,6 +214,11 @@ export interface RunQueryOptions {
      *  belt to that check's suspenders, since data can grow between a dry
      *  run and the real job, or a caller can skip the dry run entirely. */
     maximumBytesBilled?: number;
+    /** Fails the job with a typed `JobTimeoutError` once it runs longer than
+     *  this many milliseconds, wall-clock from job creation — set on the job's
+     *  own `configuration.jobTimeoutMs` (BigQuery enforces it server-side),
+     *  not a client-side `Promise.race`. */
+    jobTimeoutMs?: number;
 }
 export interface QueryPage<T = Record<string, unknown>> {
     rows: T[];
@@ -202,6 +234,10 @@ export interface EstimateQueryBytesOptions {
     /** When given, `estimateQueryBytes` throws `DryRunBudgetExceededError`
      *  instead of returning once the estimate exceeds this many bytes. */
     maxBytesBilled?: number;
+    /** Same `configuration.jobTimeoutMs` enforcement as `RunQueryOptions` —
+     *  applies to the dry-run job itself, not the (never-run) query it
+     *  estimates. */
+    jobTimeoutMs?: number;
 }
 export interface DryRunEstimate {
     totalBytesProcessed: number;
@@ -216,6 +252,10 @@ export interface DryRunEstimate {
      *  checks every entry against its own read-only table allowlist before
      *  ever submitting the real job. */
     referencedTables?: BigQueryTableReference[];
+    /** BigQuery's own result schema for the query, typed directly from the
+     *  dry-run job's `statistics.query.schema` — never inferred client-side.
+     *  `undefined` only when BigQuery's dry-run statistics omitted it. */
+    schema?: BigQueryResultSchemaField[];
 }
 export interface ExtractTableToGCSInput {
     datasetId: string;

package/dist/chat/index.d.ts

@@ -41,32 +41,63 @@
  *     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`):
+ * Usage — the MCP server the dispatched agent's clean room actually runs (AK-34): a
+ * `.danxbot/config/mcp-servers/*.yml` launches the PUBLISHED `app-kit-chat-mcp` bin
+ * directly, no vendored copy and no local install in the app's own repo. This
+ * package publishes FIVE bins and none is named `app-kit`, so `npx` needs
+ * `--package=` to say which package to fetch, separately from which bin to run —
+ * `npx -y @flytedesk/app-kit@<v> app-kit-chat-mcp` fails ("could not determine
+ * executable to run"); this is the form that actually works (verified against a real
+ * `npm pack` tarball run via `npx --package=<tgz>` from a clean directory with no
+ * `node_modules` — see `mcp/entry.test.ts`):
  *
- *   import {
- *     createChatMcpProtocol,
- *     createChatMcpStdioServer,
- *     createReplyTool,
- *   } from "@flytedesk/app-kit/chat";
+ *   server:
+ *     command: npx
+ *     args:
+ *       - "-y"
+ *       - "--package=@flytedesk/app-kit@6.0.0"
+ *       - "app-kit-chat-mcp"
+ *       - "--tools"
+ *       - "${DANX_REPO_ROOT}/packages/audience-chat-mcp/src/chatTools.mjs"
  *
- *   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();
+ * `--tools <path>` MUST be absolute — danxbot's cwd for this process is its own
+ * clean room, never assumed to equal the app's repo root, hence the
+ * `${DANX_REPO_ROOT}`-prefixed path above rather than a bare relative one.
+ *
+ * The path names the ONE thing this package cannot supply itself: the app's own
+ * tools module. That module must NOT `import` anything from `@flytedesk/app-kit` —
+ * a bare package import cannot resolve from danxbot's unbuilt dispatch clone (no
+ * `node_modules`). Instead, `app-kit-chat-mcp` INJECTS the pieces the module needs as
+ * a `ChatMcpKit` argument, and the module returns a (optionally wrapped)
+ * `ChatMcpProtocol` rather than a plain options bag:
+ *
+ *   // chatTools.mjs — the app's own file, never vendored, never copied, never
+ *   // imports @flytedesk/app-kit as a VALUE (a type-only `// @ts-check` JSDoc
+ *   // reference to BuildChatServer/ChatMcpKit is fine — see mcp/entry.ts's header)
+ *   export default function buildChatServer(kit) {
+ *     return kit.createChatMcpProtocol({
+ *       serverName: "sms-app-chat",
+ *       tools: [
+ *         kit.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 },
+ *       ],
+ *     });
+ *   }
+ *
+ * `app-kit-chat-mcp` (`src/chat/mcp/entry.ts`, published as `dist/chat/mcp/entry.js`)
+ * loads that module, calls its default export with the kit, and starts the stdio
+ * loop on whatever `ChatMcpProtocol` it returns — see `entry.ts`'s own doc comment
+ * for the full contract, why it stays dependency-free, and how a consumer (e.g.
+ * media-planner's MP-169 `loggedProtocol`) wraps `handleMessage` before returning.
  */
-export { createDanxbotLauncher, DanxbotError, isFailedJobStatus, isTerminalJobStatus } from "./launcher.js";
-export { callbackSecretMatches, requireCallbackSecret } from "./callback-secret.js";
+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";
+export type { ChatMcpStdioServer, ChatMcpStdioServerOptions, } from "./mcp-server.js";
+export type { BuildChatServer, ChatMcpKit } from "./mcp/entry.js";

package/dist/chat/index.js

@@ -41,29 +41,59 @@
  *     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`):
+ * Usage — the MCP server the dispatched agent's clean room actually runs (AK-34): a
+ * `.danxbot/config/mcp-servers/*.yml` launches the PUBLISHED `app-kit-chat-mcp` bin
+ * directly, no vendored copy and no local install in the app's own repo. This
+ * package publishes FIVE bins and none is named `app-kit`, so `npx` needs
+ * `--package=` to say which package to fetch, separately from which bin to run —
+ * `npx -y @flytedesk/app-kit@<v> app-kit-chat-mcp` fails ("could not determine
+ * executable to run"); this is the form that actually works (verified against a real
+ * `npm pack` tarball run via `npx --package=<tgz>` from a clean directory with no
+ * `node_modules` — see `mcp/entry.test.ts`):
  *
- *   import {
- *     createChatMcpProtocol,
- *     createChatMcpStdioServer,
- *     createReplyTool,
- *   } from "@flytedesk/app-kit/chat";
+ *   server:
+ *     command: npx
+ *     args:
+ *       - "-y"
+ *       - "--package=@flytedesk/app-kit@6.0.0"
+ *       - "app-kit-chat-mcp"
+ *       - "--tools"
+ *       - "${DANX_REPO_ROOT}/packages/audience-chat-mcp/src/chatTools.mjs"
  *
- *   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();
+ * `--tools <path>` MUST be absolute — danxbot's cwd for this process is its own
+ * clean room, never assumed to equal the app's repo root, hence the
+ * `${DANX_REPO_ROOT}`-prefixed path above rather than a bare relative one.
+ *
+ * The path names the ONE thing this package cannot supply itself: the app's own
+ * tools module. That module must NOT `import` anything from `@flytedesk/app-kit` —
+ * a bare package import cannot resolve from danxbot's unbuilt dispatch clone (no
+ * `node_modules`). Instead, `app-kit-chat-mcp` INJECTS the pieces the module needs as
+ * a `ChatMcpKit` argument, and the module returns a (optionally wrapped)
+ * `ChatMcpProtocol` rather than a plain options bag:
+ *
+ *   // chatTools.mjs — the app's own file, never vendored, never copied, never
+ *   // imports @flytedesk/app-kit as a VALUE (a type-only `// @ts-check` JSDoc
+ *   // reference to BuildChatServer/ChatMcpKit is fine — see mcp/entry.ts's header)
+ *   export default function buildChatServer(kit) {
+ *     return kit.createChatMcpProtocol({
+ *       serverName: "sms-app-chat",
+ *       tools: [
+ *         kit.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 },
+ *       ],
+ *     });
+ *   }
+ *
+ * `app-kit-chat-mcp` (`src/chat/mcp/entry.ts`, published as `dist/chat/mcp/entry.js`)
+ * loads that module, calls its default export with the kit, and starts the stdio
+ * loop on whatever `ChatMcpProtocol` it returns — see `entry.ts`'s own doc comment
+ * for the full contract, why it stays dependency-free, and how a consumer (e.g.
+ * media-planner's MP-169 `loggedProtocol`) wraps `handleMessage` before returning.
  */
-export { createDanxbotLauncher, DanxbotError, isFailedJobStatus, isTerminalJobStatus } from "./launcher.js";
-export { callbackSecretMatches, requireCallbackSecret } from "./callback-secret.js";
+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";

package/dist/chat/index.js.map

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/chat/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AACH,OAAO,EACL,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAC9B,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/mcp/entry.d.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { createChatMcpProtocol, createReplyTool, parseReplyArguments, type ChatMcpProtocol } from "../mcp-protocol.js";
+/**
+ * Everything a `--tools` module needs, injected rather than imported — see this
+ * file's own doc comment for why a runtime `import "@flytedesk/app-kit/chat"` from
+ * the module itself cannot work in danxbot's unbuilt dispatch clone.
+ */
+export interface ChatMcpKit {
+    createReplyTool: typeof createReplyTool;
+    parseReplyArguments: typeof parseReplyArguments;
+    createChatMcpProtocol: typeof createChatMcpProtocol;
+}
+/** The contract a `--tools` module's default export must satisfy: given the kit,
+ *  return a (possibly wrapped) `ChatMcpProtocol`. */
+export type BuildChatServer = (kit: ChatMcpKit) => ChatMcpProtocol | Promise<ChatMcpProtocol>;
+export declare class ChatMcpEntryError extends Error {
+}
+export interface ChatMcpEntryArgs {
+    /** Path to the app's tools module. MUST be absolute in real dispatch use (see this
+     *  file's own doc comment) — resolved against `process.cwd()` only as a fallback
+     *  for a genuinely relative path, which `path.resolve` leaves untouched when the
+     *  input is already absolute. */
+    toolsPath: string;
+}
+/** Parse argv into `{toolsPath}`. Exported for direct unit testing. */
+export declare function parseArgs(argv: string[]): ChatMcpEntryArgs;
+/**
+ * Dynamically `import()` the app's tools module and validate its default export.
+ * Exported for direct unit testing (no process spawn needed to exercise the loading
+ * and validation logic — see entry.test.ts's own split between a fast in-process
+ * suite for this function and real stdio/npx spawn suites for the whole process).
+ */
+export declare function loadBuildChatServer(toolsPath: string): Promise<BuildChatServer>;
+/** Run the server: load the tools module, build the protocol (via the injected
+ *  kit), and start stdio. Exported for direct unit testing of argument/validation
+ *  failures without a process spawn. */
+export declare function main(argv: string[]): Promise<void>;