@indigoai-us/hq-cli 5.108.0 → 5.108.2

package/dist/lib/work-context/organize.js

@@ -0,0 +1,471 @@
+/**
+ * hq mesh context organize — one-time decisions and US-005B submit (US-007B).
+ *
+ * CLI only presents server candidates and submits structured decisions.
+ * Ranking is server-owned. Success is reported only from the server receipt.
+ * Cancel / timeout / incapable surface leaves the session unresolved; the CLI
+ * never invents a project or adhoc target and never repeats the ask.
+ */
+import * as crypto from "node:crypto";
+import { WORK_CONTEXT_CONTRACT_VERSION } from "./contract.js";
+import { NotTrackingError } from "./errors.js";
+import { shouldAskAfter } from "./project.js";
+import { mergeLocalSessionFields, readSessionState, writeSessionState, } from "./state.js";
+/** Stable decision id for a session + expiry window. */
+export function stableDecisionId(sessionId, decisionExpiresAt) {
+    const h = crypto
+        .createHash("sha256")
+        .update(`dec:v1:${sessionId}:${decisionExpiresAt}`)
+        .digest("hex")
+        .slice(0, 24);
+    return `dec_${h}`;
+}
+export function digestOrganizePayload(parts) {
+    const canonical = JSON.stringify({
+        v: 1,
+        sessionId: parts.sessionId,
+        companyUid: parts.companyUid,
+        decision: parts.decision,
+        expectedVersion: parts.expectedVersion,
+    });
+    return crypto.createHash("sha256").update(canonical).digest("hex").slice(0, 64);
+}
+export function stableOrganizeOperationId(sessionId, decision) {
+    const h = crypto
+        .createHash("sha256")
+        .update(`organize:v1:${sessionId}:${decision.kind}:${decision.projectId ?? ""}:${decision.taskId ?? ""}:${decision.title ?? ""}`)
+        .digest("hex")
+        .slice(0, 32);
+    return `op_${h}`;
+}
+/**
+ * Build a pending decision from server candidates. Soft evidence ranks on the
+ * server; the CLI never auto-binds from this list.
+ */
+export function decisionFromCandidates(sessionId, response) {
+    const options = response.candidates.map((c) => ({
+        optionId: c.candidateId,
+        label: c.taskId
+            ? `${c.projectName} / ${c.title}`
+            : c.projectName || c.title || c.projectId,
+        kind: "bind_existing",
+        projectId: c.projectId,
+        ...(c.taskId ? { taskId: c.taskId } : {}),
+    }));
+    options.push({
+        optionId: "opt_create_project",
+        label: "Create new project",
+        kind: "create_project",
+    });
+    options.push({
+        optionId: "opt_untracked",
+        label: "Leave untracked (local only)",
+        kind: "untracked",
+    });
+    return {
+        decisionId: stableDecisionId(sessionId, response.decisionExpiresAt),
+        options,
+        expiresAt: response.decisionExpiresAt,
+        askAfter: true,
+    };
+}
+/**
+ * Evaluate work-signal threshold and, when crossed for the first time, attach
+ * a one-time decision (optionally from server candidates). Never invents a
+ * project. If a decision already exists, it is left untouched (ask-once).
+ */
+export async function prepareOrganizeDecision(input) {
+    const nowFn = input.now ?? (() => new Date());
+    const state = readSessionState(input.sessionId, input.root);
+    if (!state) {
+        return {
+            sessionId: input.sessionId,
+            contextStatus: "unresolved",
+            pending: false,
+            decision: null,
+            reason: "no_state",
+        };
+    }
+    if (state.contextStatus === "bound") {
+        return {
+            sessionId: input.sessionId,
+            contextStatus: state.contextStatus,
+            pending: false,
+            decision: state.decision ?? null,
+            reason: "already_bound",
+        };
+    }
+    if (state.contextStatus === "untracked") {
+        return {
+            sessionId: input.sessionId,
+            contextStatus: state.contextStatus,
+            pending: false,
+            decision: null,
+            reason: "untracked",
+        };
+    }
+    if (state.contextStatus === "needs_company" ||
+        state.contextStatus === "company_conflict") {
+        return {
+            sessionId: input.sessionId,
+            contextStatus: state.contextStatus,
+            pending: Boolean(state.decision),
+            decision: state.decision ?? null,
+            reason: state.contextStatus,
+        };
+    }
+    // Ask-once: an existing decision is never replaced or re-armed.
+    if (state.decision?.decisionId) {
+        return {
+            sessionId: input.sessionId,
+            contextStatus: state.contextStatus,
+            pending: true,
+            decision: state.decision,
+            reason: state.decision.askAfter ? "pending_ask" : "ask_already_settled",
+        };
+    }
+    const ready = shouldAskAfter({
+        toolWrites: state.toolWrites,
+        startedAt: state.startedAt,
+        hasTurn: state.hasTurn,
+        now: nowFn(),
+    });
+    if (!ready) {
+        return {
+            sessionId: input.sessionId,
+            contextStatus: state.contextStatus,
+            pending: false,
+            decision: null,
+            reason: "below_work_signal_threshold",
+        };
+    }
+    if (!state.companyUid || input.offline || !input.fetchCandidates) {
+        // Threshold crossed but no network — record a local placeholder so we
+        // do not invent a project; askAfter stays false until candidates arrive.
+        return {
+            sessionId: input.sessionId,
+            contextStatus: state.contextStatus,
+            pending: false,
+            decision: null,
+            reason: "candidates_unavailable",
+        };
+    }
+    const response = await input.fetchCandidates({
+        sessionId: input.sessionId,
+        companyUid: state.companyUid,
+    });
+    const decision = decisionFromCandidates(input.sessionId, response);
+    const updatedAt = nowFn().toISOString();
+    const next = mergeLocalSessionFields({
+        ...state,
+        decision,
+        contextStatus: state.contextStatus === "needs_task" ? "needs_task" : "needs_project",
+        updatedAt,
+    }, state);
+    writeSessionState(next, input.root);
+    return {
+        sessionId: input.sessionId,
+        contextStatus: next.contextStatus,
+        pending: true,
+        decision,
+        reason: "ask_prepared",
+    };
+}
+export function formatOrganizeList(result) {
+    const lines = [
+        `session ${result.sessionId} status=${result.contextStatus}` +
+            (result.reason ? ` (${result.reason})` : ""),
+    ];
+    if (!result.decision) {
+        lines.push("No pending decision.");
+        return lines;
+    }
+    lines.push(`decisionId=${result.decision.decisionId}`);
+    if (result.decision.expiresAt) {
+        lines.push(`expiresAt=${result.decision.expiresAt}`);
+    }
+    if (result.decision.correctionPath) {
+        lines.push(`correctionPath=${result.decision.correctionPath}`);
+    }
+    lines.push(`askAfter=${result.decision.askAfter === true}`);
+    for (const opt of result.decision.options) {
+        const bits = [`  ${opt.optionId}`];
+        if (opt.label)
+            bits.push(opt.label);
+        if (opt.kind)
+            bits.push(`kind=${opt.kind}`);
+        if (opt.projectId)
+            bits.push(`project=${opt.projectId}`);
+        if (opt.taskId)
+            bits.push(`task=${opt.taskId}`);
+        lines.push(bits.join("  "));
+    }
+    return lines;
+}
+/**
+ * Mark that the ask was cancelled / timed out / surface incapable.
+ * Leaves the session unresolved and visible; clears askAfter so the CLI
+ * never repeats the ask; never invents a project.
+ */
+export function settleOrganizeAskWithoutBind(input) {
+    const state = readSessionState(input.sessionId, input.root);
+    if (!state)
+        return null;
+    if (state.contextStatus === "bound" || state.contextStatus === "untracked") {
+        return state;
+    }
+    const now = (input.now ?? (() => new Date()))().toISOString();
+    const decision = state.decision
+        ? {
+            ...state.decision,
+            askAfter: false,
+        }
+        : {
+            decisionId: `settled_${input.sessionId}`,
+            options: [],
+            askAfter: false,
+        };
+    const next = mergeLocalSessionFields({
+        ...state,
+        contextStatus: state.contextStatus === "needs_company" ||
+            state.contextStatus === "company_conflict"
+            ? state.contextStatus
+            : "unresolved",
+        decision,
+        // Drop any speculative project/task — never invent.
+        projectId: undefined,
+        taskId: undefined,
+        updatedAt: now,
+    }, state);
+    // Explicitly clear project/task on disk projection.
+    const written = {
+        contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+        sessionId: next.sessionId,
+        contextStatus: next.contextStatus,
+        updatedAt: now,
+        decision,
+    };
+    if (next.companyUid)
+        written.companyUid = next.companyUid;
+    if (next.companySlug)
+        written.companySlug = next.companySlug;
+    if (typeof next.toolWrites === "number")
+        written.toolWrites = next.toolWrites;
+    if (next.startedAt)
+        written.startedAt = next.startedAt;
+    if (next.hasTurn)
+        written.hasTurn = true;
+    if (next.source)
+        written.source = next.source;
+    writeSessionState(written, input.root);
+    return written;
+}
+/**
+ * Submit an organize decision through US-005B. Success only from receipt.
+ */
+export async function submitOrganizeDecision(input) {
+    const state = readSessionState(input.sessionId, input.root);
+    if (!state) {
+        return {
+            ok: false,
+            errorCode: "NO_STATE",
+            message: `No work-context state for session ${input.sessionId}`,
+        };
+    }
+    if (input.untracked) {
+        const now = (input.now ?? (() => new Date()))().toISOString();
+        writeSessionState({
+            contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+            sessionId: input.sessionId,
+            contextStatus: "untracked",
+            untrackedReceipt: { origin: "user", at: now, noBackfill: true },
+            updatedAt: now,
+            ...(typeof state.toolWrites === "number"
+                ? { toolWrites: state.toolWrites }
+                : {}),
+            ...(state.startedAt ? { startedAt: state.startedAt } : {}),
+        }, input.root);
+        return { ok: true, localUntracked: true };
+    }
+    let decision;
+    let decisionExpiresAt;
+    if (input.createProjectTitle?.trim()) {
+        decision = {
+            kind: "create_project",
+            title: input.createProjectTitle.trim(),
+        };
+    }
+    else if (input.createTaskTitle?.trim()) {
+        const projectId = state.projectId ||
+            state.decision?.options.find((o) => o.projectId)?.projectId;
+        if (!projectId) {
+            return {
+                ok: false,
+                errorCode: "PROJECT_REQUIRED",
+                message: "create-task requires an existing projectId on the session",
+            };
+        }
+        decision = {
+            kind: "create_task",
+            projectId,
+            title: input.createTaskTitle.trim(),
+        };
+    }
+    else if (input.decisionId && input.optionId) {
+        const pending = state.decision;
+        if (!pending || pending.decisionId !== input.decisionId) {
+            return {
+                ok: false,
+                errorCode: "DECISION_MISMATCH",
+                message: "decisionId does not match the pending local decision",
+            };
+        }
+        decisionExpiresAt = pending.expiresAt;
+        const opt = pending.options.find((o) => o.optionId === input.optionId);
+        if (!opt) {
+            return {
+                ok: false,
+                errorCode: "OPTION_NOT_FOUND",
+                message: `Unknown optionId ${input.optionId}`,
+            };
+        }
+        if (opt.kind === "untracked") {
+            return submitOrganizeDecision({
+                ...input,
+                untracked: true,
+                decisionId: undefined,
+                optionId: undefined,
+            });
+        }
+        if (opt.kind === "create_project") {
+            return {
+                ok: false,
+                errorCode: "TITLE_REQUIRED",
+                message: "Use --create-project <title> to create a project (option alone has no title)",
+            };
+        }
+        if (opt.kind === "create_task") {
+            return {
+                ok: false,
+                errorCode: "TITLE_REQUIRED",
+                message: "Use --create-task <title> to create a task (option alone has no title)",
+            };
+        }
+        if (!opt.projectId) {
+            return {
+                ok: false,
+                errorCode: "OPTION_INCOMPLETE",
+                message: "Selected option has no projectId",
+            };
+        }
+        decision = {
+            kind: "bind_existing",
+            projectId: opt.projectId,
+            ...(opt.taskId ? { taskId: opt.taskId } : {}),
+        };
+    }
+    else {
+        return {
+            ok: false,
+            errorCode: "INVALID_ARGS",
+            message: "Provide --decision + --option, --create-project, --create-task, or --untracked",
+        };
+    }
+    if (decision === undefined) {
+        return { ok: false, errorCode: "INVALID_ARGS", message: "No decision" };
+    }
+    if (!state.companyUid) {
+        return {
+            ok: false,
+            errorCode: "COMPANY_REQUIRED",
+            message: "Session has no verified companyUid; cannot organize on server",
+        };
+    }
+    if (!input.postOrganize) {
+        return {
+            ok: false,
+            errorCode: "OFFLINE",
+            message: "No organize transport; server receipt required for success",
+        };
+    }
+    // Stale decision → typed error (caller may refresh candidates).
+    if (decisionExpiresAt) {
+        const exp = Date.parse(decisionExpiresAt);
+        if (Number.isFinite(exp) && Date.now() >= exp) {
+            return {
+                ok: false,
+                errorCode: "DECISION_EXPIRED",
+                message: "organization decision has expired; refresh candidates",
+            };
+        }
+    }
+    const expectedVersion = 0;
+    const operationId = stableOrganizeOperationId(input.sessionId, decision);
+    const digest = digestOrganizePayload({
+        sessionId: input.sessionId,
+        companyUid: state.companyUid,
+        decision,
+        expectedVersion,
+    });
+    let receipt;
+    try {
+        receipt = await input.postOrganize({
+            sessionId: input.sessionId,
+            companyUid: state.companyUid,
+            operationId,
+            digest,
+            decision,
+            expectedVersion,
+            ...(decisionExpiresAt ? { decisionExpiresAt } : {}),
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (/DECISION_EXPIRED|409/.test(message)) {
+            return { ok: false, errorCode: "DECISION_EXPIRED", message };
+        }
+        if (/WORK_TARGET_UNAVAILABLE|404/.test(message)) {
+            return { ok: false, errorCode: "WORK_TARGET_UNAVAILABLE", message };
+        }
+        return { ok: false, errorCode: "ORGANIZE_FAILED", message };
+    }
+    // Success only from receipt.
+    if (!receipt?.receipt?.operationId ||
+        receipt.contextStatus !== "bound" ||
+        !receipt.projectId ||
+        !receipt.bindingEpisodeId) {
+        return {
+            ok: false,
+            errorCode: "RECEIPT_INCOMPLETE",
+            message: "Server response missing authoritative binding receipt",
+        };
+    }
+    const now = (input.now ?? (() => new Date()))().toISOString();
+    try {
+        writeSessionState(mergeLocalSessionFields({
+            contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+            sessionId: input.sessionId,
+            companyUid: receipt.companyUid || state.companyUid,
+            companySlug: state.companySlug,
+            contextStatus: "bound",
+            projectId: receipt.projectId,
+            ...(receipt.taskId ? { taskId: receipt.taskId } : {}),
+            bindingEpisodeId: receipt.bindingEpisodeId,
+            updatedAt: now,
+            // Clear ask — decision resolved.
+            decision: undefined,
+        }, state), input.root);
+    }
+    catch (err) {
+        if (err instanceof NotTrackingError) {
+            return {
+                ok: false,
+                errorCode: "NOT_TRACKING",
+                message: err.message,
+            };
+        }
+        throw err;
+    }
+    return { ok: true, receipt };
+}
+//# sourceMappingURL=organize.js.map

package/dist/lib/work-context/outbox.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Metadata-only durable outbox under ~/.hq/work-context/outbox/<operationId>.json.
+ * Written before any network I/O. FIFO per session; bounded-parallel across sessions.
+ */
+import type { DeliveryState } from "./contract.js";
+import { WORK_CONTEXT_CONTRACT_VERSION } from "./contract.js";
+/** Fields allowed on a durable outbox operation (privacy allowlist). */
+export declare const OUTBOX_ALLOWLIST: readonly ["contractVersion", "operationId", "clientOperationId", "sessionId", "companyUid", "companySlug", "projectId", "taskId", "kind", "digest", "delivery", "createdAt", "updatedAt", "attemptCount", "lastErrorCode", "receiptId", "destinationCompanyUid", "destinationCompanySlug"];
+export type OutboxKind = "register" | "reconcile" | "migrate";
+export interface OutboxOperation {
+    contractVersion: typeof WORK_CONTEXT_CONTRACT_VERSION;
+    operationId: string;
+    clientOperationId: string;
+    sessionId: string;
+    companyUid?: string;
+    companySlug?: string;
+    projectId?: string;
+    taskId?: string;
+    kind: OutboxKind;
+    digest: string;
+    delivery: DeliveryState;
+    createdAt: string;
+    updatedAt: string;
+    attemptCount: number;
+    lastErrorCode?: string;
+    receiptId?: string;
+    /** Destination company for kind=migrate (source is companyUid). */
+    destinationCompanyUid?: string;
+    destinationCompanySlug?: string;
+}
+export interface OutboxEnqueueInput {
+    clientOperationId: string;
+    sessionId: string;
+    companyUid?: string;
+    companySlug?: string;
+    projectId?: string;
+    taskId?: string;
+    kind?: OutboxKind;
+    destinationCompanyUid?: string;
+    destinationCompanySlug?: string;
+    now?: () => Date;
+}
+export declare function stableOperationId(clientOperationId: string, sessionId: string): string;
+export declare function digestOperation(parts: {
+    sessionId: string;
+    clientOperationId: string;
+    companyUid?: string;
+    companySlug?: string;
+    projectId?: string;
+    taskId?: string;
+    kind: OutboxKind;
+    destinationCompanyUid?: string;
+    destinationCompanySlug?: string;
+}): string;
+/**
+ * Atomically enqueue (or idempotently return) an outbox operation.
+ * Disk/permission/lock failure → NotTrackingError (no network-only send).
+ */
+export declare function enqueueOutbox(input: OutboxEnqueueInput, root: string): OutboxOperation;
+export declare function readOutboxOperation(operationId: string, root: string): OutboxOperation | null;
+export declare function updateOutboxOperation(op: OutboxOperation, root: string): void;
+export declare function markOutboxAcked(operationId: string, root: string, receiptId: string, now?: () => Date): OutboxOperation | null;
+export declare function markOutboxQueued(operationId: string, root: string, errorCode: string, now?: () => Date): OutboxOperation | null;
+export declare function markOutboxQuarantined(operationId: string, root: string, errorCode: string, now?: () => Date): OutboxOperation | null;
+export declare function listOutboxOperations(root: string): OutboxOperation[];
+export interface OutboxStats {
+    depth: number;
+    quarantined: number;
+    queued: number;
+    acked: number;
+}
+export declare function outboxStats(root: string): OutboxStats;
+export type DeliverFn = (op: OutboxOperation) => Promise<{
+    ok: true;
+    receiptId: string;
+} | {
+    ok: false;
+    retryable: boolean;
+    code: string;
+}>;
+/**
+ * Replay queued (and recover lost-receipt) operations.
+ * FIFO per sessionId; bounded parallelism across sessions.
+ */
+export declare function replayOutbox(root: string, deliver: DeliverFn, opts?: {
+    parallel?: number;
+    now?: () => Date;
+}): Promise<{
+    delivered: number;
+    queued: number;
+    quarantined: number;
+}>;
+/** Remove acked ops older than retention (optional GC; not required by AC). */
+export declare function removeAckedOutbox(root: string, olderThanMs: number, now?: number): number;
+export declare function outboxFileExists(operationId: string, root: string): boolean;
+export declare function quarantineCorruptOutboxFile(filePath: string, root: string): void;
+//# sourceMappingURL=outbox.d.ts.map