@xfey/tutti 0.1.0

package/dist/collaboration-state/scratchpad.js

@@ -0,0 +1,84 @@
+import { nowIso, parseJson, stringifyJson } from "./serialization.js";
+export function createEmptyScratchpadProjection() {
+    return {
+        id: "current",
+        state: "empty",
+        topic: "",
+        background_summary: "",
+        current_consensus: [],
+        open_questions: [],
+        task_changes: [],
+    };
+}
+export function upsertScratchpadProjection(db, input) {
+    const updatedAt = nowIso(input.now);
+    db.prepare(`
+      INSERT INTO scratchpad (
+        id,
+        topic,
+        background_summary,
+        current_consensus_json,
+        open_questions_json,
+        task_changes_json,
+        updated_by_activity_ref,
+        updated_at
+      )
+      VALUES (
+        'current',
+        ?,
+        ?,
+        ?,
+        ?,
+        ?,
+        ?,
+        ?
+      )
+      ON CONFLICT(id) DO UPDATE SET
+        topic = excluded.topic,
+        background_summary = excluded.background_summary,
+        current_consensus_json = excluded.current_consensus_json,
+        open_questions_json = excluded.open_questions_json,
+        task_changes_json = excluded.task_changes_json,
+        updated_by_activity_ref = excluded.updated_by_activity_ref,
+        updated_at = excluded.updated_at
+    `).run(input.topic, input.background_summary, stringifyJson(input.current_consensus), stringifyJson(input.open_questions), stringifyJson(input.task_changes), input.updated_by_activity_ref ?? null, updatedAt);
+    return readScratchpadProjection(db);
+}
+export function clearScratchpadProjection(db) {
+    db.prepare("DELETE FROM scratchpad WHERE id = 'current'").run();
+    return createEmptyScratchpadProjection();
+}
+export function readScratchpadProjection(db) {
+    const row = db
+        .prepare(`
+        SELECT
+          topic,
+          background_summary,
+          current_consensus_json,
+          open_questions_json,
+          task_changes_json,
+          updated_by_activity_ref,
+          updated_at
+        FROM scratchpad
+        WHERE id = 'current'
+      `)
+        .get();
+    if (row === undefined) {
+        return createEmptyScratchpadProjection();
+    }
+    const scratchpad = {
+        id: "current",
+        state: "ready",
+        topic: row.topic,
+        background_summary: row.background_summary,
+        current_consensus: parseJson(row.current_consensus_json, []),
+        open_questions: parseJson(row.open_questions_json, []),
+        task_changes: parseJson(row.task_changes_json, []),
+        updated_at: row.updated_at,
+    };
+    if (row.updated_by_activity_ref !== null) {
+        scratchpad.updated_by_activity_ref = row.updated_by_activity_ref;
+    }
+    return scratchpad;
+}
+//# sourceMappingURL=scratchpad.js.map

package/dist/collaboration-state/serialization.d.ts

@@ -0,0 +1,16 @@
+import type { MessageProjection, TaskContractProjection } from "@tutti/shared/schemas/api";
+import type { PageCursor, TimelineCursor } from "./storage-types.js";
+export declare class CollaborationStateCursorError extends Error {
+    readonly statusCode = 400;
+    readonly code = "bad_request";
+    constructor();
+}
+export declare function clampLimit(limit: number | undefined): number;
+export declare function parseJson<T>(json: string, fallback: T): T;
+export declare function parseTaskContractJson(json: string): TaskContractProjection;
+export declare function stringifyJson(value: unknown): string;
+export declare function nowIso(now: (() => Date) | undefined): string;
+export declare function encodeCursor(cursor: TimelineCursor | PageCursor): string;
+export declare function decodeCursor(cursor: string | undefined): TimelineCursor | null;
+export declare function messageCursor(message: MessageProjection): string;
+//# sourceMappingURL=serialization.d.ts.map

package/dist/collaboration-state/serialization.js

@@ -0,0 +1,71 @@
+import { Buffer } from "node:buffer";
+export class CollaborationStateCursorError extends Error {
+    statusCode = 400;
+    code = "bad_request";
+    constructor() {
+        super("Cursor is invalid");
+        this.name = "CollaborationStateCursorError";
+    }
+}
+export function clampLimit(limit) {
+    if (limit === undefined) {
+        return 50;
+    }
+    return Math.min(Math.max(Math.trunc(limit), 1), 200);
+}
+export function parseJson(json, fallback) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return fallback;
+    }
+}
+function stringArrayFromJson(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+export function parseTaskContractJson(json) {
+    const value = parseJson(json, null);
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return { goal: "", scope: [] };
+    }
+    const record = value;
+    return {
+        goal: typeof record.goal === "string" ? record.goal : "",
+        scope: stringArrayFromJson(record.scope),
+    };
+}
+export function stringifyJson(value) {
+    return JSON.stringify(value);
+}
+export function nowIso(now) {
+    return (now ?? (() => new Date()))().toISOString();
+}
+export function encodeCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+export function decodeCursor(cursor) {
+    if (cursor === undefined || cursor.trim() === "") {
+        return null;
+    }
+    try {
+        const value = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if (typeof value === "object" &&
+            value !== null &&
+            !Array.isArray(value) &&
+            typeof value.created_at === "string" &&
+            typeof value.id === "string") {
+            return value;
+        }
+    }
+    catch {
+        throw new CollaborationStateCursorError();
+    }
+    throw new CollaborationStateCursorError();
+}
+export function messageCursor(message) {
+    return encodeCursor({ created_at: message.created_at, id: message.id });
+}
+//# sourceMappingURL=serialization.js.map

package/dist/collaboration-state/storage-types.d.ts

@@ -0,0 +1,136 @@
+import type { ClarificationRoundRef, ClarificationThreadRef, MessageId, RecoverySummaryId } from "@tutti/shared/ids";
+export type MessageRow = {
+    id: MessageId;
+    scope_kind: "main_chat" | "clarification_round";
+    clarification_round_id: string | null;
+    author_kind: "human" | "system" | "agent";
+    author_ref: string | null;
+    author_display_name: string | null;
+    author_avatar_json: string | null;
+    message_kind: "user_text" | "agent_text" | "system_notice" | "clarification_request" | "clarification_card";
+    body: string;
+    refs_json: string | null;
+    created_at: string;
+};
+export type ScratchpadRow = {
+    topic: string;
+    background_summary: string;
+    current_consensus_json: string;
+    open_questions_json: string;
+    task_changes_json: string;
+    updated_by_activity_ref: string | null;
+    updated_at: string;
+};
+export type ScratchpadSourceStateRow = {
+    main_chat_cursor_created_at: string | null;
+    main_chat_cursor_message_id: string | null;
+    task_compile_cursor_submitted_at: string | null;
+    task_compile_cursor_round_id: string | null;
+    dirty_since: string | null;
+    in_flight_activity_ref: string | null;
+    in_flight_started_at: string | null;
+    last_completed_at: string | null;
+    last_failed_at: string | null;
+    backoff_until: string | null;
+    updated_at: string;
+};
+export type TaskModuleRow = {
+    id: string;
+    name: string;
+    summary: string | null;
+    sort_order: number;
+    archived: number;
+    created_at: string;
+    updated_at: string | null;
+};
+export type TaskRow = {
+    id: string;
+    module_id: string;
+    title: string;
+    summary: string;
+    status: "todo" | "running" | "pending" | "done" | "failed";
+    sort_order: number;
+    current_activity_ref: string | null;
+    active_clarification_thread_id: string | null;
+    latest_run_result_id: string | null;
+    created_from_workflow_ref: string;
+    created_at: string;
+    updated_at: string;
+};
+export type TaskDetailRow = {
+    task_id: string;
+    contract_json: string;
+    result_json: string;
+    frozen_contract_since_activity_ref: string | null;
+    updated_at: string;
+};
+export type RunResultRow = {
+    id: string;
+    activity_ref: string;
+    task_id: string;
+    run_lineage_json: string;
+    result_kind: "needs_human" | "finished" | "failed";
+    result_json: string;
+    created_at: string;
+};
+export type RecoverySummaryRow = {
+    id: RecoverySummaryId;
+    affected_activities_json: string;
+    summary: string;
+    created_at: string;
+};
+export type ClarificationThreadRow = {
+    id: ClarificationThreadRef;
+    owner_kind: "task_compile" | "task";
+    owner_workflow_ref: string | null;
+    owner_task_id: string | null;
+    status: "active" | "closed";
+    current_round_id: string | null;
+    created_from_activity_ref: string | null;
+    closed_reason: "resolved" | "contract_changed" | "cancelled" | null;
+    created_at: string;
+    updated_at: string;
+};
+export type ClarificationRoundRow = {
+    id: ClarificationRoundRef;
+    clarification_thread_id: ClarificationThreadRef;
+    round_index: number;
+    status: "writable" | "sealed";
+    request_payload_json: string;
+    card_message_id: MessageId;
+    opening_message_id: MessageId;
+    submitted_at: string | null;
+    submitted_message_refs_json: string | null;
+    submitted_interaction_response_id: string | null;
+    successor_status: "not_materialized" | "materialized";
+    successor_ref_json: string | null;
+    created_at: string;
+    updated_at: string;
+};
+export type TimelineCursor = {
+    created_at: string;
+    id: string;
+};
+export type PageCursor = {
+    created_at: string;
+    id: string;
+};
+export type ReadStateScopeRow = "chat" | "worklist" | "references" | "skills";
+export type ReadNotificationEventRow = {
+    event_cursor: number;
+    scope: ReadStateScopeRow;
+    source_kind: string;
+    source_ref: string;
+    actor_kind: "human" | "system" | "agent" | null;
+    actor_ref: string | null;
+    occurred_at: string;
+    created_at: string;
+};
+export type ReadStateCursorRow = {
+    account_ref: string;
+    scope: ReadStateScopeRow;
+    read_event_cursor: number;
+    read_at: string;
+    updated_at: string;
+};
+//# sourceMappingURL=storage-types.d.ts.map

package/dist/collaboration-state/storage-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=storage-types.js.map

package/dist/collaboration-state/task-details.d.ts

@@ -0,0 +1,5 @@
+import type { TaskId } from "@tutti/shared/ids";
+import type { TaskDetailProjection } from "@tutti/shared/schemas/api";
+import type { SqliteDatabase } from "../store/index.js";
+export declare function readTaskDetailProjection(db: SqliteDatabase, taskId: TaskId): TaskDetailProjection | null;
+//# sourceMappingURL=task-details.d.ts.map

package/dist/collaboration-state/task-details.js

@@ -0,0 +1,25 @@
+import { parseJson, parseTaskContractJson } from "./serialization.js";
+import { readTaskProjection } from "./worklist.js";
+export function readTaskDetailProjection(db, taskId) {
+    const task = readTaskProjection(db, taskId);
+    if (task === null) {
+        return null;
+    }
+    const row = db
+        .prepare("SELECT * FROM task_details WHERE task_id = ?")
+        .get(taskId);
+    if (row === undefined) {
+        return null;
+    }
+    const detail = {
+        task_id: taskId,
+        contract: parseTaskContractJson(row.contract_json),
+        result: parseJson(row.result_json, {}),
+        updated_at: row.updated_at,
+    };
+    if (row.frozen_contract_since_activity_ref !== null) {
+        detail.frozen_contract_since_activity_ref = row.frozen_contract_since_activity_ref;
+    }
+    return { task, detail };
+}
+//# sourceMappingURL=task-details.js.map

package/dist/collaboration-state/types.d.ts

@@ -0,0 +1,289 @@
+import type { RunLineage } from "@tutti/shared/domain";
+import type { AccountAvatarProjection } from "@tutti/shared/domain";
+import type { ActivityRef, ClarificationRoundRef, TaskId, TaskModuleId, WorkflowInvocationRef } from "@tutti/shared/ids";
+import type { ClarificationRequestPayload, ClarificationRoundProjection, ClarificationSuccessorRef, ClarificationThreadProjection, MessageProjection, ReadStateScope, ReadStateSummaryProjection, RecoverySummaryProjection, RunResultProjection, TaskContractProjection, TaskDetailProjection, TaskDetailResultProjection, TaskProjection, WorklistProjection } from "@tutti/shared/schemas/api";
+export type MessageAuthorInput = {
+    kind: "human" | "system" | "agent";
+    ref?: string;
+    display_name?: string;
+    avatar?: AccountAvatarProjection;
+};
+export type RecordReadNotificationEventInput = {
+    scope: ReadStateScope;
+    source_kind: string;
+    source_ref: string;
+    actor?: {
+        kind: MessageAuthorInput["kind"];
+        ref?: string;
+    };
+    occurred_at: string;
+    created_at?: string;
+};
+export type ReadReadStateSummaryInput = {
+    account_ref: string;
+    session_created_at: string;
+    now?: () => Date;
+};
+export type MarkReadStateScopeInput = ReadReadStateSummaryInput & {
+    scope: ReadStateScope;
+    up_to_event_cursor?: number;
+};
+export type MarkReadStateScopeResult = {
+    read_state: ReadStateSummaryProjection;
+};
+export type CreateMainChatMessageInput = {
+    body: string;
+    author: MessageAuthorInput;
+    refs?: MessageProjection["refs"];
+    now?: () => Date;
+};
+export type CreateMainChatSystemMessageInput = {
+    body: string;
+    refs?: MessageProjection["refs"];
+    now?: () => Date;
+};
+export type CreateMainChatAgentMessageInput = {
+    body: string;
+    refs?: MessageProjection["refs"];
+    now?: () => Date;
+};
+export type ScratchpadSnapshotInput = {
+    topic: string;
+    background_summary: string;
+    current_consensus: string[];
+    open_questions: string[];
+    task_changes: string[];
+    updated_by_activity_ref?: ActivityRef;
+    now?: () => Date;
+};
+export type TaskCompileProposalInput = {
+    workflow_ref: WorkflowInvocationRef;
+    proposal: {
+        modules: TaskCompileProposalModuleInput[];
+        tasks: TaskCompileProposalTaskInput[];
+    };
+    now?: () => Date;
+};
+export type TaskCompileProposalModuleInput = {
+    temp_key: string;
+    name: string;
+};
+export type TaskCompileProposalTaskInput = {
+    module_temp_key?: string;
+    existing_module_key?: TaskModuleId;
+    title: string;
+    summary: string;
+    contract: TaskContractProjection;
+};
+export type ApplyTaskCompileProposalResult = {
+    worklist: WorklistProjection;
+    changed_module_ids: TaskModuleId[];
+    changed_task_ids: TaskId[];
+};
+export type NextRunnableTaskResult = {
+    kind: "found";
+    task: TaskProjection;
+    queued_task_ids: TaskId[];
+} | {
+    kind: "none";
+};
+export type MarkTaskRunStartedInput = {
+    task_id: TaskId;
+    activity_ref: ActivityRef;
+    now?: () => Date;
+};
+export type MarkTaskRunStartedResult = {
+    kind: "started";
+    task: TaskProjection;
+} | {
+    kind: "not_found";
+} | {
+    kind: "not_runnable";
+    task: TaskProjection;
+};
+export type RunResultPromotionProjection = NonNullable<TaskDetailResultProjection["promotion"]>;
+export type RecordRunResultInput = {
+    activity_ref: ActivityRef;
+    task_id: TaskId;
+    run_lineage: RunLineage;
+    result: {
+        result_kind: "finished";
+        outcome: "completed" | "failed";
+        summary: string;
+        checks: "passed" | "failed" | "skipped";
+        docs: "updated" | "checked_no_change" | "not_checked" | "sync_deferred";
+        skip_reason_code?: TaskDetailResultProjection["skip_reason_code"];
+        skip_reason_summary?: string;
+        external_side_effects?: TaskDetailResultProjection["external_side_effects"];
+        changed_paths?: string[];
+        promotion?: RunResultPromotionProjection;
+    } | {
+        result_kind: "failed";
+        summary: string;
+        error_code: string;
+        retryable: boolean;
+        changed_paths?: string[];
+        promotion?: RunResultPromotionProjection;
+    };
+    now?: () => Date;
+};
+export type RecordRunResultResult = {
+    run_result: RunResultProjection;
+    task: TaskProjection;
+    task_detail: TaskDetailProjection;
+};
+export type RecordRunNeedsHumanResultInput = {
+    activity_ref: ActivityRef;
+    task_id: TaskId;
+    run_lineage: RunLineage;
+    result: {
+        result_kind: "needs_human";
+        summary: string;
+        clarification_request_payload: ClarificationRequestPayload;
+        changed_paths?: string[];
+    };
+    now?: () => Date;
+};
+export type RecordRunNeedsHumanResultResult = {
+    run_result: RunResultProjection;
+    task: TaskProjection;
+    task_detail: TaskDetailProjection;
+    thread: ClarificationThreadProjection;
+    round: ClarificationRoundProjection;
+    card_message: MessageProjection;
+    opening_message: MessageProjection;
+};
+export type RecoverStaleRunningTasksResult = {
+    recovered_runs: Array<{
+        activity_ref: ActivityRef;
+        run_result: RunResultProjection;
+        task: TaskProjection;
+        task_detail: TaskDetailProjection;
+    }>;
+};
+export type RecordRecoverySummaryInput = {
+    summary: string;
+    affected_activities: ActivityRef[];
+    now?: () => Date;
+};
+export type RecordRecoverySummaryResult = {
+    recovery_summary: RecoverySummaryProjection;
+};
+export type RecoverableScheduledRun = {
+    task: TaskProjection;
+    activity_ref: ActivityRef;
+    queued_task_ids: TaskId[];
+};
+export type OpenTaskCompileClarificationRoundInput = {
+    workflow_ref: WorkflowInvocationRef;
+    activity_ref?: ActivityRef;
+    request_payload: ClarificationRequestPayload;
+    now?: () => Date;
+};
+export type OpenTaskCompileClarificationRoundResult = {
+    thread: ClarificationThreadProjection;
+    round: ClarificationRoundProjection;
+    card_message: MessageProjection;
+    opening_message: MessageProjection;
+};
+export type OpenNextTaskCompileClarificationRoundInput = {
+    continue_from_round_id: ClarificationRoundRef;
+    workflow_ref: WorkflowInvocationRef;
+    activity_ref?: ActivityRef;
+    request_payload: ClarificationRequestPayload;
+    now?: () => Date;
+};
+export type OpenNextTaskCompileClarificationRoundResult = OpenTaskCompileClarificationRoundResult & {
+    previous_round: ClarificationRoundProjection;
+};
+export type OpenNextTaskBoundClarificationRoundInput = {
+    continue_from_round_id: ClarificationRoundRef;
+    request_payload: ClarificationRequestPayload;
+    now?: () => Date;
+};
+export type OpenNextTaskBoundClarificationRoundResult = {
+    thread: ClarificationThreadProjection;
+    previous_round: ClarificationRoundProjection;
+    round: ClarificationRoundProjection;
+    task: TaskProjection;
+    card_message: MessageProjection;
+    opening_message: MessageProjection;
+};
+export type CreateClarificationRoundMessageInput = {
+    round_id: ClarificationRoundRef;
+    body: string;
+    author: MessageAuthorInput;
+    now?: () => Date;
+};
+export type CreateClarificationRoundAgentMessageInput = {
+    round_id: ClarificationRoundRef;
+    body: string;
+    refs?: MessageProjection["refs"];
+    now?: () => Date;
+};
+export type SubmitClarificationRoundInput = {
+    round_id: ClarificationRoundRef;
+    accepted_command_id?: string;
+    now?: () => Date;
+};
+export type MaterializeClarificationSuccessorInput = {
+    round_id: ClarificationRoundRef;
+    successor_ref: ClarificationSuccessorRef;
+    close_thread?: boolean;
+    closed_reason?: "resolved" | "contract_changed" | "cancelled";
+    now?: () => Date;
+};
+export type MaterializeTaskBoundRunSuccessorInput = {
+    round_id: ClarificationRoundRef;
+    activity_ref: ActivityRef;
+    now?: () => Date;
+};
+export type MaterializeTaskBoundRunSuccessorResult = {
+    kind: "materialized";
+    thread: ClarificationThreadProjection;
+    round: ClarificationRoundProjection;
+    task: TaskProjection;
+} | {
+    kind: "already_materialized";
+    thread: ClarificationThreadProjection;
+    round: ClarificationRoundProjection;
+    task: TaskProjection | null;
+};
+export type CloseTaskBoundClarificationRetaskingRequiredInput = {
+    round_id: ClarificationRoundRef;
+    summary: string;
+    now?: () => Date;
+};
+export type CloseTaskBoundClarificationRetaskingRequiredResult = {
+    kind: "closed";
+    thread: ClarificationThreadProjection;
+    round: ClarificationRoundProjection;
+    task: TaskProjection;
+    task_detail: TaskDetailProjection;
+    message: MessageProjection;
+} | {
+    kind: "already_materialized";
+    thread: ClarificationThreadProjection;
+    round: ClarificationRoundProjection;
+    task: TaskProjection | null;
+    task_detail: TaskDetailProjection | null;
+};
+export type SealedClarificationRoundWithoutSuccessor = {
+    thread: ClarificationThreadProjection;
+    round: ClarificationRoundProjection;
+};
+export type ReadMessageWindowOptions = {
+    limit?: number;
+    anchor?: "latest" | "start";
+    before?: string;
+    after?: string;
+};
+export type ReadMainChatMessagesAfterOptions = {
+    after_created_at: string;
+    limit?: number;
+};
+export type CursorPageOptions = {
+    cursor?: string;
+    limit?: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/collaboration-state/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/collaboration-state/worklist.d.ts

@@ -0,0 +1,11 @@
+import { type TaskId } from "@tutti/shared/ids";
+import type { TaskProjection, WorklistProjection } from "@tutti/shared/schemas/api";
+import type { SqliteDatabase } from "../store/index.js";
+import type { ApplyTaskCompileProposalResult, MarkTaskRunStartedInput, MarkTaskRunStartedResult, NextRunnableTaskResult, RecoverableScheduledRun, TaskCompileProposalInput } from "./types.js";
+export declare function readTaskProjection(db: SqliteDatabase, taskId: TaskId): TaskProjection | null;
+export declare function readWorklistProjection(db: SqliteDatabase): WorklistProjection;
+export declare function readNextRunnableTask(db: SqliteDatabase): NextRunnableTaskResult;
+export declare function readRecoverableScheduledRun(db: SqliteDatabase): RecoverableScheduledRun | null;
+export declare function markTaskRunStarted(db: SqliteDatabase, input: MarkTaskRunStartedInput): MarkTaskRunStartedResult;
+export declare function applyTaskCompileProposal(db: SqliteDatabase, input: TaskCompileProposalInput): ApplyTaskCompileProposalResult;
+//# sourceMappingURL=worklist.d.ts.map