@arnilo/prism-coding-agent 0.2.5 → 0.2.6

package/dist/workspace-lifecycle.d.ts

@@ -0,0 +1,153 @@
+import type { ArtifactReference, GitOperations } from "./git.js";
+/** Separate versioned namespace: never collides with coding checkpoint v1 keys. */
+export declare const WORKSPACE_NAMESPACE: "prism.coding-agent.workspace.v1";
+export declare const WORKSPACE_SCHEMA_VERSION: 1;
+export declare const WORKSPACE_LOCK_REASON_PREFIX: "prism-workspace:";
+/** Frozen workspace state machine: active | cleaning | closed | unknown. */
+export type WorkspaceState = "active" | "cleaning" | "closed" | "unknown";
+export declare const WORKSPACE_STATES: readonly WorkspaceState[];
+export type WorkspaceRepositoryState = "active" | "removed" | "unknown";
+export type WorkspaceErrorCode = "ERR_PRISM_WORKSPACE_UNKNOWN" | "ERR_PRISM_WORKSPACE_LIMIT" | "ERR_PRISM_WORKSPACE_OWNERSHIP" | "ERR_PRISM_WORKSPACE_FENCE" | "ERR_PRISM_WORKSPACE_DIRTY" | "ERR_PRISM_WORKSPACE_LOCKED" | "ERR_PRISM_WORKSPACE_MAIN" | "ERR_PRISM_WORKSPACE_PATH_ESCAPE" | "ERR_PRISM_WORKSPACE_FINGERPRINT";
+export declare class WorkspaceError extends Error {
+    readonly code: WorkspaceErrorCode;
+    constructor(code: WorkspaceErrorCode, message: string);
+}
+/** Host-approved repository registration; `git` must be cwd-bound to `root`. */
+export interface WorkspaceRepositoryRegistration {
+    readonly root: string;
+    readonly git: GitOperations;
+}
+/** Durable per-repository leg of a workspace record. */
+export interface WorkspaceRepositoryRecord {
+    readonly repositoryId: string;
+    /** Canonical absolute root; the main worktree is immutable. */
+    readonly root: string;
+    /** Credential-free remote fingerprint (sha256 hex), never a URL. */
+    readonly remoteFingerprint: string;
+    readonly defaultBranch?: string;
+    readonly branch: string;
+    /** Branch base at create time. */
+    readonly base: string;
+    /** Verified head at create/last verify. */
+    readonly head: string;
+    readonly worktreeId: string;
+    readonly worktreePath: string;
+    readonly state: WorkspaceRepositoryState;
+    readonly createdAt: string;
+}
+/** Durable workspace record (schemaVersion 1, namespace WORKSPACE_NAMESPACE). */
+export interface CodingWorkspaceRecord {
+    readonly schemaVersion: typeof WORKSPACE_SCHEMA_VERSION;
+    readonly workspaceId: string;
+    readonly taskId: string;
+    readonly ownerId: string;
+    readonly state: WorkspaceState;
+    readonly repositories: readonly WorkspaceRepositoryRecord[];
+    /** Artifact references only; never artifact contents or credentials. */
+    readonly artifactRefs: readonly ArtifactReference[];
+    /** Lease fencing token at last mutation; monotonic per record. */
+    readonly fencingToken: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly cleanupAt?: string;
+}
+export interface WorkspaceCreateRequest {
+    readonly taskId: string;
+    readonly repositories: readonly {
+        readonly repositoryId: string;
+        readonly branch: string;
+    }[];
+    readonly artifactRefs?: readonly ArtifactReference[];
+    readonly signal?: AbortSignal;
+}
+/** Host policy gates the documented cleanup refusals; all default to refuse. */
+export interface WorkspaceCleanupPolicy {
+    /** Allow forced removal of dirty worktrees (potential data loss). */
+    readonly allowDirtyCleanup?: boolean;
+    /** Allow unlocking worktrees locked by an external actor. */
+    readonly allowLockedCleanup?: boolean;
+    /** Allow claiming a missing worktree as removed. */
+    readonly allowMissingCleanup?: boolean;
+    /** Allow unclaiming a path that exists but is not a registered worktree. */
+    readonly allowUnownedCleanup?: boolean;
+    /** Allow forced removal when the worktree head no longer matches the record. */
+    readonly allowMismatchedCleanup?: boolean;
+}
+export interface WorkspaceLimitOptions {
+    readonly maxRepositories?: number;
+    readonly maxWorktrees?: number;
+    readonly maxRecordBytes?: number;
+    readonly leaseTtlMs?: number;
+    readonly maxCleanupOperations?: number;
+}
+export interface ResolvedWorkspaceLimits {
+    readonly maxRepositories: number;
+    readonly maxWorktrees: number;
+    readonly maxRecordBytes: number;
+    readonly leaseTtlMs: number;
+    readonly maxCleanupOperations: number;
+}
+export declare function resolveWorkspaceLimits(options?: WorkspaceLimitOptions): ResolvedWorkspaceLimits;
+export interface CreateCodingWorkspaceLifecycleOptions {
+    readonly checkpoints: import("@arnilo/prism").CheckpointStore;
+    readonly leases: import("@arnilo/prism").LeaseStore;
+    /** Replica/worker identity; part of the fencing trust boundary. */
+    readonly ownerId: string;
+    readonly ownership?: import("@arnilo/prism").OwnershipScope;
+    /** Host-approved repositories keyed by repositoryId. */
+    readonly repositories: Readonly<Record<string, WorkspaceRepositoryRegistration>>;
+    /** Host-approved linked-worktree destination roots (canonicalized). */
+    readonly worktreeRoots: readonly string[];
+    readonly policy?: WorkspaceCleanupPolicy;
+    readonly limits?: WorkspaceLimitOptions;
+}
+export interface CodingWorkspaceLifecycle {
+    /**
+     * Create linked worktrees for a task and persist the workspace record.
+     * Idempotent: an identical active record returns as-is (no Git mutation).
+     * Stale or conflicting workers fail with ERR_PRISM_WORKSPACE_FENCE.
+     */
+    create(request: WorkspaceCreateRequest): Promise<CodingWorkspaceRecord>;
+    get(input: {
+        readonly taskId: string;
+        readonly signal?: AbortSignal;
+    }): Promise<CodingWorkspaceRecord | null>;
+    list(input?: {
+        readonly cursor?: string;
+        readonly limit?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<{
+        readonly items: readonly CodingWorkspaceRecord[];
+        readonly nextCursor?: string;
+    }>;
+    /**
+     * Resume gate: revalidates repository/worktree identity and fingerprints
+     * (root containment, worktree presence, head, remote/default-branch) before
+     * tools, processes, index results, patches, or artifacts are reused.
+     */
+    verify(input: {
+        readonly taskId: string;
+        readonly signal?: AbortSignal;
+    }): Promise<CodingWorkspaceRecord>;
+    attachArtifacts(input: {
+        readonly taskId: string;
+        readonly artifactRefs: readonly ArtifactReference[];
+        readonly signal?: AbortSignal;
+    }): Promise<CodingWorkspaceRecord>;
+    /**
+     * Remove owned linked worktrees and close the record. Refuses dirty, locked,
+     * unowned, missing, or mismatched trees unless the host policy allows the
+     * documented action; partial failure persists state `unknown` and remains
+     * reconcilable by retrying.
+     */
+    cleanup(input: {
+        readonly taskId: string;
+        readonly signal?: AbortSignal;
+    }): Promise<CodingWorkspaceRecord>;
+    /** Delete the durable record (no Git mutation); false when absent. */
+    remove(input: {
+        readonly taskId: string;
+        readonly signal?: AbortSignal;
+    }): Promise<boolean>;
+}
+export declare function createCodingWorkspaceLifecycle(options: CreateCodingWorkspaceLifecycleOptions): CodingWorkspaceLifecycle;