@ishlabs/cli 0.17.6 → 0.18.0

package/dist/lib/profile-sources.d.ts

@@ -1,33 +1,45 @@
 /**
- * Audience source upload + processing lifecycle.
+ * Participant attachment upload + processing lifecycle.
  *
- * Mirrors the frontend flow in ensure-sources-processed.ts and
- * UploadSection.tsx:
- *   1. POST /tester-profiles/sources/initiate → signed URL + source_id
- *   2. PUT  signed_url                         → upload bytes (x-upsert: true)
- *   3. POST /tester-profiles/sources/{id}/confirm → kick off parse / transcribe
- *   4. GET  /tester-profiles/sources/{id}      → poll until terminal status
+ * Mirrors the frontend flow in the creation flow's upload hook:
+ *   1. POST /people/attachments/initiate       → signed URL + attachment_id
+ *   2. PUT  signed_url                                  → upload bytes (x-upsert: true)
+ *   3. POST /people/attachments/{id}/confirm   → kick off parse / transcribe
+ *   4. GET  /people/attachments/{id}           → poll until terminal status
  *
  * Distinct from the study upload in upload.ts: different endpoints and a
  * fourth polling step because text/image are parsed inline but audio is
  * transcribed by an async worker.
+ *
+ * The public CLI command name `source` is preserved for compatibility; the
+ * internal vocabulary tracks the unified `attachments` model (ADR-0034).
  */
 import type { ApiClient } from "./api-client.js";
-import type { AudienceSource, SourceKind } from "./types.js";
+import type { Attachment, AttachmentKind, GenerationJob } from "./types.js";
 /**
- * Map a local file to the backend's SourceKind enum.
+ * Map a local file to the backend's AttachmentKind enum.
  * Throws if the extension/MIME isn't recognized — caller can pass an
  * explicit `kind` to override.
  */
-export declare function inferSourceKind(filePath: string): SourceKind;
+export declare function inferAttachmentKind(filePath: string): AttachmentKind;
+/** Back-compat re-export: the public CLI keeps the `source` vocabulary. */
+export declare const inferSourceKind: typeof inferAttachmentKind;
 export declare function isUuid(value: string): boolean;
-/** Poll a source until it reaches a terminal status or the timeout fires. */
-export declare function pollSourceUntilTerminal(client: ApiClient, sourceId: string, timeoutMs?: number): Promise<AudienceSource>;
+/** Poll an attachment until it reaches a terminal status or the timeout fires. */
+export declare function pollAttachmentUntilTerminal(client: ApiClient, attachmentId: string, timeoutMs?: number): Promise<Attachment>;
+/** Back-compat alias. */
+export declare const pollSourceUntilTerminal: typeof pollAttachmentUntilTerminal;
 export interface UploadAndProcessOpts {
     productId: string;
     filePath: string;
-    kind?: SourceKind;
+    kind?: AttachmentKind;
     description?: string;
+    /**
+     * Retained for CLI compat — the new /attachments/confirm endpoint does NOT
+     * accept a diarize flag (audio confirm always runs the diarization-capable
+     * worker). The value is ignored; callers can keep passing --diarize until
+     * the flag is dropped in a follow-up.
+     */
     diarize?: boolean;
     /** When false, return after confirm without polling. Default true. */
     wait?: boolean;
@@ -36,7 +48,9 @@ export interface UploadAndProcessOpts {
     quiet?: boolean;
 }
 /** Run the full initiate → PUT → confirm → poll cycle for a single file. */
-export declare function uploadAndProcessSource(client: ApiClient, opts: UploadAndProcessOpts): Promise<AudienceSource>;
+export declare function uploadAndProcessAttachment(client: ApiClient, opts: UploadAndProcessOpts): Promise<Attachment>;
+/** Back-compat alias for callers still importing the `Source` name. */
+export declare const uploadAndProcessSource: typeof uploadAndProcessAttachment;
 export interface ResolveSourceRefOpts {
     productId: string;
     description?: string;
@@ -47,9 +61,43 @@ export interface ResolveSourceRefOpts {
 }
 /**
  * Resolve a `--source` value: a UUID is returned as-is; a local path is
- * uploaded and the resulting source ID is returned.
+ * uploaded and the resulting attachment ID is returned.
  *
  * If a UUID-shaped string is provided but turns out not to be a real
- * source, the backend rejects it on /generate — no need to pre-check.
+ * attachment, the backend rejects it on /generate — no need to pre-check.
  */
 export declare function resolveSourceRef(client: ApiClient, value: string, opts: ResolveSourceRefOpts): Promise<string>;
+/**
+ * Thrown when a generation job doesn't reach a terminal status before the
+ * --timeout fires. Carries `error_code`/`retryable`/`progress` so the JSON
+ * error envelope (output.ts) surfaces them — the job keeps running
+ * server-side, so the agent can re-poll the same job id rather than re-enqueue.
+ */
+export declare class GenerationTimeoutError extends Error {
+    readonly progress: {
+        job_id: string;
+        timeout_seconds: number;
+        status: string;
+        progress_message: string | null;
+    };
+    readonly error_code = "wait_timeout";
+    readonly retryable = true;
+    constructor(message: string, progress: {
+        job_id: string;
+        timeout_seconds: number;
+        status: string;
+        progress_message: string | null;
+    });
+}
+export interface PollGenerationJobOpts {
+    timeoutMs?: number;
+    /** Print status progress lines to stderr. Default true unless quiet. */
+    quiet?: boolean;
+}
+/**
+ * Poll a generation job until it reaches `completed` or `failed`, or the
+ * timeout fires. Emits a stderr line each time `progress_message`/`status`
+ * changes so agents see the ~30-60s run isn't stuck (mirrors the attachment-poll
+ * UX). Returns the terminal job; callers branch on `status` themselves.
+ */
+export declare function pollGenerationJobUntilDone(client: ApiClient, jobId: string, opts?: PollGenerationJobOpts): Promise<GenerationJob>;

package/dist/lib/profile-sources.js

@@ -1,16 +1,18 @@
 /**
- * Audience source upload + processing lifecycle.
+ * Participant attachment upload + processing lifecycle.
  *
- * Mirrors the frontend flow in ensure-sources-processed.ts and
- * UploadSection.tsx:
- *   1. POST /tester-profiles/sources/initiate → signed URL + source_id
- *   2. PUT  signed_url                         → upload bytes (x-upsert: true)
- *   3. POST /tester-profiles/sources/{id}/confirm → kick off parse / transcribe
- *   4. GET  /tester-profiles/sources/{id}      → poll until terminal status
+ * Mirrors the frontend flow in the creation flow's upload hook:
+ *   1. POST /people/attachments/initiate       → signed URL + attachment_id
+ *   2. PUT  signed_url                                  → upload bytes (x-upsert: true)
+ *   3. POST /people/attachments/{id}/confirm   → kick off parse / transcribe
+ *   4. GET  /people/attachments/{id}           → poll until terminal status
  *
  * Distinct from the study upload in upload.ts: different endpoints and a
  * fourth polling step because text/image are parsed inline but audio is
  * transcribed by an async worker.
+ *
+ * The public CLI command name `source` is preserved for compatibility; the
+ * internal vocabulary tracks the unified `attachments` model (ADR-0034).
  */
 import { readFile } from "node:fs/promises";
 import { basename, extname, resolve as resolvePath } from "node:path";
@@ -33,11 +35,11 @@ const TEXT_EXTS = new Set([
     ".docx",
 ]);
 /**
- * Map a local file to the backend's SourceKind enum.
+ * Map a local file to the backend's AttachmentKind enum.
  * Throws if the extension/MIME isn't recognized — caller can pass an
  * explicit `kind` to override.
  */
-export function inferSourceKind(filePath) {
+export function inferAttachmentKind(filePath) {
     const ext = extname(filePath).toLowerCase();
     if (AUDIO_EXTS.has(ext))
         return "audio";
@@ -57,8 +59,10 @@ export function inferSourceKind(filePath) {
         mime.includes("officedocument")) {
         return "text_file";
     }
-    throw new Error(`Cannot infer source kind for ${filePath}. Pass --kind text_file|audio|image to override.`);
+    throw new Error(`Cannot infer attachment kind for ${filePath}. Pass --kind text_file|audio|image to override.`);
 }
+/** Back-compat re-export: the public CLI keeps the `source` vocabulary. */
+export const inferSourceKind = inferAttachmentKind;
 export function isUuid(value) {
     return UUID_RE.test(value);
 }
@@ -68,7 +72,7 @@ async function putFileToSignedUrl(signedUrl, filePath, mime) {
     // Supabase signed-upload endpoint authenticates via the ?token=... query
     // string already in the URL. Adding Authorization: Bearer here makes
     // Supabase fall through to JWT validation and 400s on PDFs (see frontend
-    // putAudienceSourceFile comment).
+    // putAttachmentFile comment).
     const res = await fetch(signedUrl, {
         method: "PUT",
         headers: {
@@ -80,42 +84,43 @@ async function putFileToSignedUrl(signedUrl, filePath, mime) {
     });
     if (!res.ok) {
         const body = await res.text().catch(() => "");
-        throw new Error(`Source upload failed (HTTP ${res.status} ${res.statusText})${body ? ` — ${body.slice(0, 500)}` : ""}`);
+        throw new Error(`Attachment upload failed (HTTP ${res.status} ${res.statusText})${body ? ` — ${body.slice(0, 500)}` : ""}`);
     }
 }
-/** Poll a source until it reaches a terminal status or the timeout fires. */
-export async function pollSourceUntilTerminal(client, sourceId, timeoutMs = DEFAULT_POLL_TIMEOUT_MS) {
+/** Poll an attachment until it reaches a terminal status or the timeout fires. */
+export async function pollAttachmentUntilTerminal(client, attachmentId, timeoutMs = DEFAULT_POLL_TIMEOUT_MS) {
     const deadline = Date.now() + timeoutMs;
     while (true) {
-        const source = await client.get(`/tester-profiles/sources/${sourceId}`);
-        if (TERMINAL_STATUSES.has(source.status))
-            return source;
+        const attachment = await client.get(`/people/attachments/${attachmentId}`);
+        if (TERMINAL_STATUSES.has(attachment.status))
+            return attachment;
         if (Date.now() >= deadline) {
-            throw new Error(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for source ${sourceId} (status: ${source.status})`);
+            throw new Error(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for attachment ${attachmentId} (status: ${attachment.status})`);
         }
         await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
     }
 }
+/** Back-compat alias. */
+export const pollSourceUntilTerminal = pollAttachmentUntilTerminal;
 /** Run the full initiate → PUT → confirm → poll cycle for a single file. */
-export async function uploadAndProcessSource(client, opts) {
+export async function uploadAndProcessAttachment(client, opts) {
     const resolved = resolvePath(opts.filePath);
     const { mime } = await validateFile(opts.filePath);
     const fileName = basename(resolved);
-    const kind = opts.kind ?? inferSourceKind(opts.filePath);
+    const kind = opts.kind ?? inferAttachmentKind(opts.filePath);
     const log = (msg) => {
         if (!opts.quiet)
             process.stderr.write(msg);
     };
     log(`Uploading ${fileName}…`);
-    const init = await client.post("/tester-profiles/sources/initiate", {
+    const init = await client.post("/people/attachments/initiate", {
         product_id: opts.productId,
         file_name: fileName,
         content_type: mime,
         kind,
     }, { timeout: 60_000 });
     await putFileToSignedUrl(init.signed_url, resolved, mime);
-    const confirmed = await client.post(`/tester-profiles/sources/${init.source_id}/confirm`, {
-        diarize: opts.diarize,
+    const confirmed = await client.post(`/people/attachments/${init.attachment_id}/confirm`, {
         description: opts.description,
     }, { timeout: 60_000 });
     if (opts.wait === false) {
@@ -127,21 +132,23 @@ export async function uploadAndProcessSource(client, opts) {
         return confirmed;
     }
     log(" processing…");
-    const final = await pollSourceUntilTerminal(client, init.source_id, opts.timeoutMs ?? DEFAULT_POLL_TIMEOUT_MS);
+    const final = await pollAttachmentUntilTerminal(client, init.attachment_id, opts.timeoutMs ?? DEFAULT_POLL_TIMEOUT_MS);
     log(` ${final.status}.\n`);
     return final;
 }
+/** Back-compat alias for callers still importing the `Source` name. */
+export const uploadAndProcessSource = uploadAndProcessAttachment;
 /**
  * Resolve a `--source` value: a UUID is returned as-is; a local path is
- * uploaded and the resulting source ID is returned.
+ * uploaded and the resulting attachment ID is returned.
  *
  * If a UUID-shaped string is provided but turns out not to be a real
- * source, the backend rejects it on /generate — no need to pre-check.
+ * attachment, the backend rejects it on /generate — no need to pre-check.
  */
 export async function resolveSourceRef(client, value, opts) {
     if (isUuid(value))
         return value;
-    const source = await uploadAndProcessSource(client, {
+    const attachment = await uploadAndProcessAttachment(client, {
         productId: opts.productId,
         filePath: value,
         description: opts.description,
@@ -150,8 +157,62 @@ export async function resolveSourceRef(client, value, opts) {
         timeoutMs: opts.timeoutMs,
         quiet: opts.quiet,
     });
-    if (source.status === "failed") {
-        throw new Error(`Source ${source.original_filename} failed to process: ${source.error ?? "unknown error"}`);
+    if (attachment.status === "failed") {
+        throw new Error(`Attachment ${attachment.file_name} failed to process: ${attachment.error ?? "unknown error"}`);
+    }
+    return attachment.id;
+}
+// --- Agentic generation jobs ---
+const GENERATION_POLL_INTERVAL_MS = 2_500;
+const GENERATION_TERMINAL_STATUSES = new Set(["completed", "failed"]);
+/**
+ * Thrown when a generation job doesn't reach a terminal status before the
+ * --timeout fires. Carries `error_code`/`retryable`/`progress` so the JSON
+ * error envelope (output.ts) surfaces them — the job keeps running
+ * server-side, so the agent can re-poll the same job id rather than re-enqueue.
+ */
+export class GenerationTimeoutError extends Error {
+    progress;
+    error_code = "wait_timeout";
+    retryable = true;
+    constructor(message, progress) {
+        super(message);
+        this.progress = progress;
+        this.name = "GenerationTimeoutError";
+    }
+}
+/**
+ * Poll a generation job until it reaches `completed` or `failed`, or the
+ * timeout fires. Emits a stderr line each time `progress_message`/`status`
+ * changes so agents see the ~30-60s run isn't stuck (mirrors the attachment-poll
+ * UX). Returns the terminal job; callers branch on `status` themselves.
+ */
+export async function pollGenerationJobUntilDone(client, jobId, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 600_000;
+    const deadline = Date.now() + timeoutMs;
+    let lastReported = "";
+    while (true) {
+        const job = await client.get(`/people/generation-jobs/${jobId}`, undefined, { timeout: 60_000 });
+        if (!opts.quiet) {
+            const line = job.progress_message
+                ? `${job.status}: ${job.progress_message}`
+                : job.status;
+            if (line !== lastReported) {
+                process.stderr.write(`  ${line}\n`);
+                lastReported = line;
+            }
+        }
+        if (GENERATION_TERMINAL_STATUSES.has(job.status))
+            return job;
+        if (Date.now() >= deadline) {
+            throw new GenerationTimeoutError(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for generation job ${jobId} ` +
+                `(status: ${job.status}). The job is still running — re-poll later, don't re-enqueue.`, {
+                job_id: jobId,
+                timeout_seconds: Math.round(timeoutMs / 1000),
+                status: job.status,
+                progress_message: job.progress_message,
+            });
+        }
+        await new Promise((r) => setTimeout(r, GENERATION_POLL_INTERVAL_MS));
     }
-    return source.id;
 }