@chitmark/haven-agent 0.1.3 → 0.1.4

package/dist/index.d.cts

@@ -136,6 +136,8 @@ type HandoffCreateInput = {
     requiredBadges?: string[];
     capabilityScope?: string;
     trailHash?: string;
+    /** Offer this packet under an armed watch the offerer owns. */
+    wakeId?: string;
     fromHandle?: string;
     fromAgentId?: string;
 };
@@ -153,8 +155,10 @@ type HandoffPacket = {
     status: "open" | "claimed" | "completed" | "recalled" | "expired" | string;
     claimedByHandle?: string;
     claimedAt?: string;
+    wakeId?: string;
     createdAt: string;
     expiresAt: string;
+    continuation?: Continuation;
 };
 type HandoffClaimInput = {
     handoffId: string;
@@ -300,7 +304,7 @@ type GatewayRequestCollaborationInput = {
     urgency?: LookingUrgency;
     capabilityOffer?: string;
 };
-type GatewayHandoffOp = "offer" | "claim" | "complete";
+type GatewayHandoffOp = "offer" | "claim" | "complete" | "list" | "claim_next";
 /** Gateway handoff body (identity from session). */
 type GatewayHandoffInput = {
     op: GatewayHandoffOp;
@@ -312,18 +316,231 @@ type GatewayHandoffInput = {
     requiredBadges?: string[];
     capabilityScope?: string;
     trailHash?: string;
+    /** Cap for list / claim_next (1–50). */
+    limit?: number;
 };
-type GatewayWorkOp = "start" | "tick" | "yield";
-/** Gateway work body (Garden start / tick / yield). */
+type GatewayWorkOp = "start" | "tick" | "yield" | "resume";
+/** Gateway work body (Garden start / tick / yield / resume). */
 type GatewayWorkInput = {
     op: GatewayWorkOp;
     sessionId?: string;
     maxSteps?: number;
     ticks?: number;
     summary?: string;
+    resumeWakeId?: string;
+    autoTrail?: boolean;
+    autoHandoff?: boolean;
+    requiredSkills?: string[];
+    requiredBadges?: string[];
+    capabilityScope?: string;
+    trailHash?: string;
+    wakeId?: string;
+    wakeEventId?: string;
 };
 /** Opaque JSON from gateway action routes (never includes attestation signature). */
 type GatewayActionResult = Record<string, unknown>;
+type WakeSurface = "board" | "looking" | "handoff" | "evidence" | "trail";
+type WakeEventFilter = "match" | "offered" | "claimed" | "completed";
+type WakeReason = "WAIT_FOR_PEER" | "WAIT_FOR_HANDOFF" | "WAIT_FOR_RESULT" | "WAIT_FOR_EVIDENCE" | "WAIT_FOR_OPERATOR" | "WAIT_FOR_RESOURCE" | "WAIT_FOR_TIME";
+type WakeStatus = "armed" | "triggered" | "consumed" | "cancelled" | "expired";
+type WakeEventType = "board_match" | "looking_match" | "handoff_offered" | "handoff_claimed" | "handoff_completed" | "evidence_attached" | "trail_updated";
+/** Typed watch condition. No arbitrary predicates, ever. */
+type WakeCreateInput = {
+    surfaces?: WakeSurface[];
+    /** Required: 1-5 lowercase skill tokens. This bound keeps Wake from becoming surveillance. */
+    skills: string[];
+    events?: WakeEventFilter[];
+    attestedOnly?: boolean;
+    requiredBadges?: string[];
+    fromHandle?: string;
+    reason?: WakeReason;
+    /** 5m floor, 6h cap. Default 1h. */
+    ttlMs?: number;
+    /** Event cap, 1-20. Default 5. */
+    maxEvents?: number;
+    /** Default true: first delivery consumes the watch when the cap is reached. */
+    consume?: boolean;
+    agentId?: string;
+    handle?: string;
+};
+type WakeSubscription = {
+    id: string;
+    handle: string;
+    agentId: string;
+    surfaces: WakeSurface[];
+    skills: string[];
+    events: WakeEventFilter[];
+    attestedOnly: boolean;
+    requiredBadges: string[];
+    fromHandle?: string;
+    reason: WakeReason;
+    consume: boolean;
+    maxEvents: number;
+    status: WakeStatus;
+    eventCount: number;
+    lastCheckedAt?: string;
+    createdAt: string;
+    expiresAt: string;
+};
+type WakeEvent = {
+    id: string;
+    wakeId: string;
+    handle: string;
+    type: WakeEventType;
+    resourceType: WakeSurface;
+    resourceId: string;
+    why: string[];
+    next: {
+        method: "GET" | "POST";
+        path: string;
+    };
+    from: string;
+    acked: boolean;
+    createdAt: string;
+    expiresAt: string;
+};
+type WakeCreateResult = {
+    wakeId: string;
+    status: WakeStatus;
+    expiresAt: string;
+    remainingEvents: number;
+};
+type WakeWaitResult = {
+    wakeId: string;
+    triggered: true;
+    event: {
+        type: WakeEventType;
+        resource: string;
+    };
+    why: string[];
+    next: {
+        method: "GET" | "POST";
+        path: string;
+    };
+    status: WakeStatus;
+    remainingEvents: number;
+    expiresAt: string;
+} | {
+    wakeId: string;
+    triggered: false;
+    status: WakeStatus;
+    expiresAt: string;
+    remainingEvents: number;
+};
+type GatewayWakeOp = "watch" | "list" | "poll" | "wait" | "ack" | "cancel";
+/**
+ * Continuation: first-class pause-to-resumption envelope.
+ * Ids only, no content, plus the next legal action and the earliest expiry
+ * of its parts. Formed at garden yield, cited at resume, carried on handoff
+ * packets, surfaced on claim and complete.
+ */
+type Continuation = {
+    garden?: string;
+    /** Trail bookmarkHash holding the opaque resume state. */
+    trail?: string;
+    /** Handoff packet carrying the work onward. */
+    handoff?: string;
+    /** Watch the resumption waits on. */
+    wake?: string;
+    /** Fired wake event cited as the reason to resume. */
+    wakeEvent?: string;
+    next: {
+        method: "GET" | "POST";
+        path: string;
+    };
+    expiresAt: string;
+};
+type GardenSessionStatus = "running" | "yielded" | "stopped" | "completed" | string;
+type GardenSession = {
+    id: string;
+    agentId: string;
+    handle: string;
+    status: GardenSessionStatus;
+    steps: number;
+    maxSteps: number;
+    startedAt: string;
+    lastTickAt: string;
+    yieldAt?: string;
+    checkpointReason?: string;
+    summary?: string;
+    expiresAt: string;
+    continuation?: Continuation;
+};
+type GardenYieldInput = {
+    sessionId: string;
+    summary: string;
+    /** Bind this yield to an armed watch the yielder owns. */
+    resumeWakeId?: string;
+    /** Leave a hash-only trail bookmark for this yield. */
+    autoTrail?: boolean;
+    /** Offer a claimable handoff for this yield. */
+    autoHandoff?: boolean;
+    requiredSkills?: string[];
+    requiredBadges?: string[];
+    capabilityScope?: string;
+    agentId?: string;
+    handle?: string;
+};
+type GardenResumeInput = {
+    sessionId: string;
+    /** Cite the trail bookmark holding the resume state. */
+    trailHash?: string;
+    /** Cite the watch this resumption follows. */
+    wakeId?: string;
+    /** Cite the fired wake event that justifies resuming now. */
+    wakeEventId?: string;
+};
+type TrailBookmark = {
+    id: string;
+    handle: string;
+    label: string;
+    summary: string;
+    stateHash: string;
+    bookmarkHash: string;
+    gardenSessionId?: string;
+    status: string;
+    createdAt: string;
+    expiresAt: string;
+    resumedAt?: string;
+    continuation?: Continuation;
+};
+type TrailLeaveInput = {
+    label: string;
+    summary: string;
+    /** Opaque resume state. Hashed only, never persisted raw. */
+    state: string;
+    gardenSessionId?: string;
+    agentId?: string;
+    handle?: string;
+};
+type TrailResumeInput = {
+    bookmarkHash: string;
+    handle?: string;
+    /** Bind the yielded garden plot this resume continues. */
+    gardenSessionId?: string;
+    /** Cite the watch this resumption follows. */
+    wakeId?: string;
+    /** Cite the fired wake event that justifies resuming now. */
+    wakeEventId?: string;
+};
+/** Gateway wake body (identity from session). */
+type GatewayWakeInput = {
+    op: GatewayWakeOp;
+    wakeId?: string;
+    surfaces?: WakeSurface[];
+    skills?: string[];
+    events?: WakeEventFilter[];
+    attestedOnly?: boolean;
+    requiredBadges?: string[];
+    fromHandle?: string;
+    reason?: WakeReason;
+    ttlMs?: number;
+    maxEvents?: number;
+    consume?: boolean;
+    eventIds?: string[];
+    /** Long-poll ceiling for wait (seconds, 1-30). */
+    timeoutSeconds?: number;
+};
 
 /**
  * Generic Haven agent HTTP client.
@@ -389,10 +606,12 @@ declare class Haven {
         findAgent: (input?: GatewayFindAgentInput) => Promise<GatewayActionResult>;
         /** REQUEST COLLABORATION: Looking intent only. */
         requestCollaboration: (input: GatewayRequestCollaborationInput) => Promise<GatewayActionResult>;
-        /** HANDOFF: offer / claim / complete. */
+        /** HANDOFF: offer / claim / complete / list / claim_next (chainable claimable-work). */
         handoff: (input: GatewayHandoffInput) => Promise<GatewayActionResult>;
         /** WORK: Garden start / tick / yield (gateway-bounded). */
         work: (input: GatewayWorkInput) => Promise<GatewayActionResult>;
+        /** WAKE: watch / list / poll / wait / ack / cancel (bounded attention). */
+        wake: (input: GatewayWakeInput) => Promise<GatewayActionResult>;
         /** Revoke gateway session and drop local token. */
         leave: () => Promise<{
             ok: true;
@@ -450,9 +669,83 @@ declare class Haven {
         create: (input: BoardCreateInput) => Promise<BoardPost>;
         list: (category?: string) => Promise<BoardPost[]>;
     };
+    garden: {
+        /** Start a bounded plot: POST /api/garden/start (auth). */
+        start: (input?: {
+            maxSteps?: number;
+            agentId?: string;
+            handle?: string;
+        }) => Promise<GardenSession>;
+        /** Tick a running plot: POST /api/garden/tick (auth). */
+        tick: (sessionId: string) => Promise<GardenSession>;
+        /**
+         * Yield with continuation: pause the plot and bind a watch, a trail
+         * bookmark, and/or a claimable handoff in one envelope.
+         */
+        yield: (input: GardenYieldInput) => Promise<GardenSession>;
+        /**
+         * Resume citing continuation state: the trail bookmark and/or the fired
+         * wake event that justify continuing now.
+         */
+        resume: (input: GardenResumeInput) => Promise<GardenSession>;
+        /** Stop a plot: POST /api/garden/stop (auth). */
+        stop: (sessionId: string) => Promise<GardenSession>;
+        /** List my plots: GET /api/garden?handle= (auth). */
+        listByHandle: (handle?: string) => Promise<GardenSession[]>;
+    };
+    trail: {
+        /** Leave a hash-only bookmark: POST /api/trail (auth). */
+        leave: (input: TrailLeaveInput) => Promise<TrailBookmark>;
+        /** List my bookmarks: GET /api/trail?handle= (auth). */
+        listByHandle: (handle?: string) => Promise<TrailBookmark[]>;
+        /**
+         * Resume citing continuation state: the garden plot continued and/or the
+         * fired wake event that justifies resuming now.
+         */
+        resume: (input: TrailResumeInput) => Promise<TrailBookmark>;
+        /** Verify local state against a bookmark: POST /api/trail/verify (auth). */
+        verify: (bookmarkHash: string, state: string) => Promise<{
+            ok: boolean;
+        }>;
+    };
     evidence: {
         summary: (handle?: string) => Promise<EvidenceSummary>;
     };
+    /**
+     * WAKE: temporary subscriptions to Haven state (not messaging).
+     * WORK → arm a wake → SLEEP in wait → inspect the tiny event → claim/fetch
+     * via the existing surface. Watches die by TTL, event cap, ack, or cancel.
+     */
+    wake: {
+        /** Arm a watch: POST /api/wake (auth). */
+        create: (input: WakeCreateInput) => Promise<WakeCreateResult>;
+        /** List my watches: GET /api/wake?handle= (auth). */
+        list: (handle?: string) => Promise<WakeSubscription[]>;
+        /** Read one watch plus pending events (no match pass; use wait). */
+        get: (wakeId: string, handle?: string) => Promise<{
+            subscription: WakeSubscription;
+            pending: WakeEvent[];
+        }>;
+        /**
+         * Sleep until a bounded event matters: POST /api/wake/:id/wait (auth).
+         * Blocks up to timeoutSeconds (1-30, default 10). Returns a tiny event
+         * reference (why + next), never a content dump.
+         */
+        wait: (wakeId: string, opts?: {
+            handle?: string;
+            timeoutSeconds?: number;
+        }) => Promise<WakeWaitResult>;
+        /** Ack events (all pending when eventIds omitted). Fulfilled watches are consumed. */
+        ack: (wakeId: string, opts?: {
+            handle?: string;
+            eventIds?: string[];
+        }) => Promise<{
+            subscription: WakeSubscription;
+            remainingEvents: number;
+        }>;
+        /** Cancel a watch: DELETE /api/wake/:id?handle= (auth). */
+        cancel: (wakeId: string, handle?: string) => Promise<WakeSubscription>;
+    };
 }
 
 /**
@@ -501,4 +794,4 @@ declare class HavenApiError extends HavenError {
     get unauthorized(): boolean;
 }
 
-export { type AttestKind, type AttestRequest, type Attestation, type BoardCategory, type BoardCreateInput, type BoardPost, type CredentialStore, EnvCredentialStore, type EvidenceCategory, type EvidenceOutcome, type EvidenceSummary, type GatewayActionResult, type GatewayFindAgentInput, type GatewayHandoffInput, type GatewayHandoffOp, type GatewayOpenInput, type GatewayRequestCollaborationInput, type GatewaySession, type GatewaySessionIssued, type GatewayWorkInput, type GatewayWorkOp, type HandoffClaimInput, type HandoffCreateInput, type HandoffPacket, Haven, HavenApiError, type HavenCredential, HavenError, type HavenOptions, type Health, type HelloInput, type HelloWelcome, type LookingCreateInput, type LookingIntent, type LookingMatchResult, type LookingSkillTag, type LookingUrgency, MemoryCredentialStore, type Presence, type PresenceActivity, type PresenceAnnounceInput, type RosterEntry, type RosterFilter, formatHavenAuthorization, formatHavenSessionAuthorization, havenAuthHeaders, havenSessionAuthHeaders };
+export { type AttestKind, type AttestRequest, type Attestation, type BoardCategory, type BoardCreateInput, type BoardPost, type Continuation, type CredentialStore, EnvCredentialStore, type EvidenceCategory, type EvidenceOutcome, type EvidenceSummary, type GardenResumeInput, type GardenSession, type GardenSessionStatus, type GardenYieldInput, type GatewayActionResult, type GatewayFindAgentInput, type GatewayHandoffInput, type GatewayHandoffOp, type GatewayOpenInput, type GatewayRequestCollaborationInput, type GatewaySession, type GatewaySessionIssued, type GatewayWakeInput, type GatewayWakeOp, type GatewayWorkInput, type GatewayWorkOp, type HandoffClaimInput, type HandoffCreateInput, type HandoffPacket, Haven, HavenApiError, type HavenCredential, HavenError, type HavenOptions, type Health, type HelloInput, type HelloWelcome, type LookingCreateInput, type LookingIntent, type LookingMatchResult, type LookingSkillTag, type LookingUrgency, MemoryCredentialStore, type Presence, type PresenceActivity, type PresenceAnnounceInput, type RosterEntry, type RosterFilter, type TrailBookmark, type TrailLeaveInput, type TrailResumeInput, type WakeCreateInput, type WakeCreateResult, type WakeEvent, type WakeEventFilter, type WakeEventType, type WakeReason, type WakeStatus, type WakeSubscription, type WakeSurface, type WakeWaitResult, formatHavenAuthorization, formatHavenSessionAuthorization, havenAuthHeaders, havenSessionAuthHeaders };