newmark-agent 0.6.1 → 0.6.3

package/dist/core/continuation/contracts.d.ts

@@ -0,0 +1,197 @@
+/**
+ * continuation-v1 contracts.
+ *
+ * These are the runtime-checked boundaries shared by the PC GUI, the hosted
+ * mobile API and the isolated runtimes. A view may read a snapshot, but it can
+ * never supply the execution identity that a write is allowed to use.
+ */
+export type WorkspaceId = string;
+export type RootId = string;
+export type BranchId = string;
+export type BuildId = string;
+export type AttemptId = string;
+export type CommandId = string;
+export type SnapshotId = string;
+export declare const CONTINUATION_SCHEMA_VERSION: 1;
+export type BuildStatus = 'QUEUED' | 'RUNNING' | 'WAITING_TOOL' | 'WAITING_APPROVAL' | 'WAITING_SUBAGENT' | 'FINALIZING' | 'SUCCEEDED' | 'FAILED' | 'CANCELLED';
+export type AttemptStatus = 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'EXPIRED';
+export type ContinuationErrorCode = 'TARGET_REQUIRED' | 'ROUTE_MISMATCH' | 'QUEUE_REVISION_CONFLICT' | 'ANCHOR_NOT_IN_LINEAGE' | 'ANCHOR_NOT_COMMITTED' | 'IDEMPOTENCY_KEY_REUSE' | 'STALE_EXECUTION' | 'FINAL_ALREADY_COMMITTED' | 'BUILD_NOT_READY' | 'BRANCH_PAUSED' | 'EFFECT_UNCERTAIN' | 'UNKNOWN_BRANCH' | 'UNKNOWN_BUILD' | 'UNKNOWN_COMMAND';
+export declare class ContinuationError extends Error {
+    readonly code: ContinuationErrorCode;
+    readonly detail?: Record<string, unknown> | undefined;
+    constructor(code: ContinuationErrorCode, message: string, detail?: Record<string, unknown> | undefined);
+}
+export interface CommandTarget {
+    workspaceId: WorkspaceId;
+    expectedRootId: RootId;
+    branchId: BranchId;
+}
+export interface BuildInput {
+    text: string;
+    images?: Array<{
+        dataUrl: string;
+        name?: string;
+        type?: string;
+    }>;
+    attachments?: Array<{
+        id: string;
+        name: string;
+        mimeType: string;
+        dataUrl?: string;
+    }>;
+    requestedMode?: string;
+    goalObjective?: string;
+    /** Provider-qualified model frozen at command acceptance time. */
+    modelSelection?: string;
+    /** Branch node captured when the user submitted the command. */
+    branchNodeId?: string;
+    branchPath?: string[];
+}
+export interface EnqueueBuildCommand {
+    schemaVersion: typeof CONTINUATION_SCHEMA_VERSION;
+    type: 'ENQUEUE_BUILD';
+    commandId: CommandId;
+    actorId: string;
+    target: CommandTarget;
+    expectedTailBuildId: BuildId | null;
+    expectedQueueRevision: number;
+    input: BuildInput;
+    recipeSnapshotId: SnapshotId;
+    createdAt: string;
+}
+export interface CommandReceipt {
+    schemaVersion: typeof CONTINUATION_SCHEMA_VERSION;
+    commandId: CommandId;
+    requestHash: string;
+    workspaceId: WorkspaceId;
+    rootId: RootId;
+    branchId: BranchId;
+    buildId: BuildId;
+    parentBuildId: BuildId | null;
+    queueSequence: number;
+    queueRevision: number;
+    lifecycleRevision: number;
+    acceptedAt: string;
+    duplicate?: boolean;
+}
+export interface ExecutionScope {
+    workspaceId: WorkspaceId;
+    rootId: RootId;
+    branchId: BranchId;
+    buildId: BuildId;
+    attemptId: AttemptId;
+    fence: number;
+    parentBuildId: BuildId | null;
+    baseContextSnapshotId: SnapshotId;
+    environmentSnapshotId: SnapshotId;
+    workerCapability: string;
+}
+export interface BranchGuardSnapshot {
+    branchId: BranchId;
+    activeBuildId: BuildId | null;
+    activeAttemptId: AttemptId | null;
+    fence: number;
+    leaseUntil: number;
+    workerCapability: string;
+}
+export interface QueueSnapshot {
+    workspaceId: WorkspaceId;
+    rootId: RootId;
+    branchId: BranchId;
+    headBuildId: BuildId | null;
+    tailBuildId: BuildId | null;
+    queueRevision: number;
+    lifecycleRevision: number;
+    paused: boolean;
+    activeBuildId: BuildId | null;
+    guard: BranchGuardSnapshot;
+    builds: BuildRecord[];
+}
+export interface BuildRecord {
+    buildId: BuildId;
+    workspaceId: WorkspaceId;
+    rootId: RootId;
+    branchId: BranchId;
+    parentBuildId: BuildId | null;
+    inputHash: string;
+    input: BuildInput;
+    recipeSnapshotId: SnapshotId;
+    status: BuildStatus;
+    queueSequence: number;
+    createdAt: string;
+    updatedAt: string;
+    finalId?: string;
+    waitingReason?: string;
+}
+export interface AttemptRecord {
+    attemptId: AttemptId;
+    buildId: BuildId;
+    branchId: BranchId;
+    fence: number;
+    status: AttemptStatus;
+    leaseUntil: number;
+    workerCapability: string;
+    startedAt: string;
+    endedAt?: string;
+}
+export interface FinalRecord {
+    finalId: string;
+    buildId: BuildId;
+    branchId: BranchId;
+    finalHash: string;
+    stateSnapshotId: SnapshotId;
+    text: string;
+    committedAt: string;
+}
+export interface ContinuationEvent {
+    eventId: string;
+    cursor: number;
+    type: 'BuildAccepted' | 'AttemptStarted' | 'AttemptHeartbeat' | 'BuildCommitted' | 'BuildFailed' | 'BuildCancelled' | 'BranchForked' | 'BranchPaused' | 'BranchResumed' | 'StaleWriteRejected';
+    workspaceId: WorkspaceId;
+    rootId: RootId;
+    branchId: BranchId;
+    buildId: BuildId | null;
+    attemptId: AttemptId | null;
+    fence: number | null;
+    at: string;
+    payload?: Record<string, unknown>;
+}
+export interface LedgerFile {
+    version: typeof CONTINUATION_SCHEMA_VERSION;
+    workspaceId: WorkspaceId;
+    roots: Record<RootId, {
+        rootId: RootId;
+        workspaceId: WorkspaceId;
+        defaultBranchId: BranchId;
+        createdAt: string;
+    }>;
+    branches: Record<BranchId, BranchRecord>;
+    builds: Record<BuildId, BuildRecord>;
+    attempts: Record<AttemptId, AttemptRecord>;
+    guards: Record<BranchId, BranchGuardSnapshot>;
+    commands: Record<string, CommandReceipt>;
+    finals: Record<BuildId, FinalRecord>;
+    events: ContinuationEvent[];
+    nextEventCursor: number;
+    nextQueueSequence: number;
+}
+export interface BranchRecord {
+    branchId: BranchId;
+    workspaceId: WorkspaceId;
+    rootId: RootId;
+    parentAnchorBuildId: BuildId | null;
+    headBuildId: BuildId | null;
+    tailBuildId: BuildId | null;
+    queueRevision: number;
+    lifecycleRevision: number;
+    paused: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare function stableJson(value: unknown): string;
+export declare function emptyLedger(workspaceId: WorkspaceId): LedgerFile;
+export declare function defaultGuard(branchId: BranchId): BranchGuardSnapshot;
+export declare function commandKey(actorId: string, commandId: CommandId): string;
+export declare function buildInputHash(input: BuildInput): string;
+export declare function requestHash(command: EnqueueBuildCommand): string;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/core/continuation/contracts.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * continuation-v1 contracts.
+ *
+ * These are the runtime-checked boundaries shared by the PC GUI, the hosted
+ * mobile API and the isolated runtimes. A view may read a snapshot, but it can
+ * never supply the execution identity that a write is allowed to use.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContinuationError = exports.CONTINUATION_SCHEMA_VERSION = void 0;
+exports.stableJson = stableJson;
+exports.emptyLedger = emptyLedger;
+exports.defaultGuard = defaultGuard;
+exports.commandKey = commandKey;
+exports.buildInputHash = buildInputHash;
+exports.requestHash = requestHash;
+exports.CONTINUATION_SCHEMA_VERSION = 1;
+class ContinuationError extends Error {
+    code;
+    detail;
+    constructor(code, message, detail) {
+        super(message);
+        this.code = code;
+        this.detail = detail;
+        this.name = 'ContinuationError';
+    }
+}
+exports.ContinuationError = ContinuationError;
+function stableJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(item => stableJson(item)).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record).sort().map(key => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(',')}}`;
+}
+function emptyLedger(workspaceId) {
+    return {
+        version: exports.CONTINUATION_SCHEMA_VERSION,
+        workspaceId,
+        roots: {},
+        branches: {},
+        builds: {},
+        attempts: {},
+        guards: {},
+        commands: {},
+        finals: {},
+        events: [],
+        nextEventCursor: 1,
+        nextQueueSequence: 1,
+    };
+}
+function defaultGuard(branchId) {
+    return { branchId, activeBuildId: null, activeAttemptId: null, fence: 0, leaseUntil: 0, workerCapability: '' };
+}
+function commandKey(actorId, commandId) {
+    return `${actorId}\u0000${commandId}`;
+}
+function buildInputHash(input) {
+    return require('crypto').createHash('sha256').update(stableJson(input)).digest('hex').slice(0, 24);
+}
+function requestHash(command) {
+    return require('crypto').createHash('sha256').update(stableJson({
+        type: command.type,
+        target: command.target,
+        expectedTailBuildId: command.expectedTailBuildId,
+        expectedQueueRevision: command.expectedQueueRevision,
+        input: command.input,
+        recipeSnapshotId: command.recipeSnapshotId,
+    })).digest('hex');
+}
+//# sourceMappingURL=contracts.js.map

package/dist/core/continuation/store.d.ts

@@ -0,0 +1,178 @@
+import { BranchId, BranchRecord, BuildId, BuildInput, BuildRecord, CommandReceipt, ContinuationEvent, EnqueueBuildCommand, ExecutionScope, FinalRecord, QueueSnapshot, RootId, SnapshotId } from './contracts';
+export interface GuardedContinuationStoreOptions {
+    /** Lease duration for one attempt. */
+    leaseMs?: number;
+    /** Maximum retained append-only events per workspace ledger. */
+    eventRetention?: number;
+}
+/**
+ * Single-writer continuation ledger for one workspace.
+ *
+ * The spec's reference uses SQLite. This implementation keeps the same
+ * boundaries with a lock-file + atomic-replace JSON ledger because the project
+ * does not ship a native SQLite module and an Electron native dependency would
+ * change the packaging/signing contract. All continuation writes must go
+ * through this class; callers never mutate the ledger directly.
+ */
+export declare class GuardedContinuationStore {
+    private readonly workspacePath;
+    private readonly workspaceId;
+    private readonly ledgerPath;
+    private readonly lockPath;
+    private readonly leaseMs;
+    private readonly eventRetention;
+    private fingerprint;
+    private cached;
+    constructor(workspacePath: string, workspaceId: string, options?: GuardedContinuationStoreOptions);
+    get filePath(): string;
+    ensureRoot(rootId: RootId, defaultBranchId: BranchId): void;
+    ensureBranch(input: {
+        rootId: RootId;
+        branchId: BranchId;
+        parentAnchorBuildId: BuildId | null;
+    }): BranchRecord;
+    getReceipt(actorId: string, commandId: string): CommandReceipt | undefined;
+    enqueueBuild(command: EnqueueBuildCommand): CommandReceipt;
+    claimBuild(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        workerCapability: string;
+        now?: number;
+    }): ExecutionScope | null;
+    updateQueuedBuild(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        buildId: BuildId;
+        input: BuildInput;
+    }): BuildRecord;
+    deleteQueuedBuild(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        buildId: BuildId;
+    }): void;
+    reorderQueuedBuilds(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        orderedBuildIds: BuildId[];
+    }): QueueSnapshot;
+    heartbeat(scope: Pick<ExecutionScope, 'branchId' | 'buildId' | 'attemptId' | 'fence'>, now?: number): boolean;
+    commitFinal(input: {
+        scope: ExecutionScope;
+        text: string;
+        finalHash?: string;
+        stateSnapshotId?: SnapshotId;
+        now?: number;
+    }): FinalRecord;
+    /**
+     * Trusted external-owner completion.
+     *
+     * A Flow is a kernel-owned external run, not a leased model worker. It still
+     * has to be a durable build so queued Goal/Next successors have a committed
+     * parent. This path validates the parent/head relation transactionally but
+     * does not require a BranchGuard attempt; the kernel owns the Flow lifetime.
+     * If the build is not the next ready build, it stays QUEUED and the caller
+     * must retry after the predecessor commits.
+     */
+    commitExternalBuild(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        buildId: BuildId;
+        text?: string;
+        now?: number;
+    }): boolean;
+    /**
+     * Claim a new attempt for an existing external Flow build (suspend/resume).
+     * The build identity and fixed parent are preserved; only the attempt/fence
+     * advance. This is the external-owner equivalent of retryBuild.
+     */
+    claimExternalBuild(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        buildId: BuildId;
+        workerCapability?: string;
+        now?: number;
+    }): ExecutionScope;
+    failBuild(input: {
+        scope: ExecutionScope;
+        reason: string;
+        now?: number;
+    }): void;
+    cancelBuild(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        buildId: BuildId;
+        now?: number;
+    }): void;
+    retryBuild(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        buildId: BuildId;
+    }): BuildRecord;
+    /**
+     * Idempotent failure recovery for an input that was never accepted.
+     *
+     * Stop/archive may release the branch guard before the runtime reports the
+     * failure. In that case the build is still the same durable row and must be
+     * returned to QUEUED for an explicit resume instead of being stranded in
+     * RUNNING (or permanently FAILED). A committed build is never requeued.
+     */
+    requeueBuild(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        buildId: BuildId;
+    }): BuildRecord;
+    forkBranch(input: {
+        commandId: string;
+        actorId: string;
+        workspaceId: string;
+        sourceBranchId: BranchId;
+        anchorBuildId: BuildId;
+        newBranchId: BranchId;
+    }): BranchRecord;
+    setPaused(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        paused: boolean;
+    }): boolean;
+    snapshot(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+    }): QueueSnapshot;
+    private snapshotUnlocked;
+    events(afterCursor?: number, limit?: number): ContinuationEvent[];
+    recoverExpiredLeases(now?: number): number;
+    private terminateAttempt;
+    private releaseExpiredGuard;
+    private markDependentsBlocked;
+    private hasCommittedDescendant;
+    private isAncestorOfHead;
+    private ensureBranchRecord;
+    private requireBranch;
+    private ensureGuard;
+    /**
+     * Release the active attempt without ever moving the branch fence backward.
+     * A recovered/completed attempt's fence stays as the monotonic high-water
+     * mark; the next claim increments it again.
+     */
+    private releaseGuard;
+    private appendEvent;
+    private mutate;
+    private acquireLock;
+    private readLedger;
+    private readLedgerUnlocked;
+    private writeLedgerUnlocked;
+    private ensureLedgerExists;
+    private invalidateCache;
+}
+//# sourceMappingURL=store.d.ts.map