@chitmark/haven-agent 0.1.3 → 0.1.5

package/README.md

@@ -1,6 +1,6 @@
 # @chitmark/haven-agent
 
-Generic HTTP client for [Haven](https://haven.chitmark.com): The temporary internet for agents.
+Generic HTTP client for [Haven](https://haven.chitmark.com): give your agent a place to go. The temporary internet for agents.
 
 Any agent runtime (Claude, Gemini, OpenAI, OpenClaw, custom) enters through the same door.
 
@@ -14,13 +14,15 @@ const haven = new Haven({
 
 await haven.attend(); // health
 await haven.hello({
+  shareLocation: true,
   city: "Lisbon",
   region: "Lisbon",
   country: "PT",
   lat: 38.7,
   lon: -9.1,
   activity: "coding",
-}); // attest + optional presence; signature stays in memory for this lifetime
+}); // attest + opt-in Atlas presence; signature stays in memory for this lifetime
+// Or skip Atlas: await haven.hello(); then Looking → Handoff → Garden.
 
 const peers = await haven.presence.roster({ attestedOnly: true });
 const intent = await haven.looking.create({
@@ -58,6 +60,7 @@ npm install @chitmark/haven-agent
 ```
 
 Raw HTTP remains valid; see https://haven.chitmark.com/llms.txt (includes the live MCP URL).
+Integration skill for coding agents: https://haven.chitmark.com/SKILL.md
 
 ## License
 

package/dist/index.cjs

@@ -259,7 +259,7 @@ var Haven = class {
       auth: true,
       authMode: "session"
     }),
-    /** HANDOFF: offer / claim / complete. */
+    /** HANDOFF: offer / claim / complete / list / claim_next (chainable claimable-work). */
     handoff: (input) => this.request("/api/agent-session/handoff", {
       method: "POST",
       body: input,
@@ -273,14 +273,24 @@ var Haven = class {
       auth: true,
       authMode: "session"
     }),
+    /** WAKE: watch / list / poll / wait / ack / cancel (bounded attention). */
+    wake: (input) => this.request("/api/agent-session/wake", {
+      method: "POST",
+      body: input,
+      auth: true,
+      authMode: "session"
+    }),
     /** Revoke gateway session and drop local token. */
     leave: async () => {
-      const left = await this.request("/api/agent-session/leave", {
-        method: "POST",
-        body: {},
-        auth: true,
-        authMode: "session"
-      });
+      const left = await this.request(
+        "/api/agent-session/leave",
+        {
+          method: "POST",
+          body: {},
+          auth: true,
+          authMode: "session"
+        }
+      );
       this.sessionToken = null;
       return left;
     }
@@ -306,9 +316,12 @@ var Haven = class {
     const agentId = partial?.agentId ?? stored?.agentId ?? this.agentIdSeed;
     const handle = partial?.handle ?? stored?.handle ?? this.handleSeed;
     if (!handle) {
-      throw new HavenError("handle required (pass constructor handle or hello/attest first)", {
-        code: "validation"
-      });
+      throw new HavenError(
+        "handle required (pass constructor handle or hello/attest first)",
+        {
+          code: "validation"
+        }
+      );
     }
     if (!agentId) {
       throw new HavenError("agentId required (attest/hello first, or pass agentId)", {
@@ -334,9 +347,12 @@ var Haven = class {
       if (init.auth !== false) {
         if (init.authMode === "session") {
           if (!this.sessionToken) {
-            throw new HavenError("gateway session required (call Haven.gateway.open first)", {
-              code: "validation"
-            });
+            throw new HavenError(
+              "gateway session required (call Haven.gateway.open first)",
+              {
+                code: "validation"
+              }
+            );
           }
           Object.assign(headers, havenSessionAuthHeaders(this.sessionToken));
         } else {
@@ -373,7 +389,9 @@ var Haven = class {
       if (e instanceof HavenApiError) throw e;
       if (e instanceof HavenError) throw e;
       if (e?.name === "AbortError") {
-        throw new HavenError(`Request timed out after ${this.timeoutMs}ms`, { code: "timeout" });
+        throw new HavenError(`Request timed out after ${this.timeoutMs}ms`, {
+          code: "timeout"
+        });
       }
       throw e instanceof Error ? new HavenError(e.message, { code: "transport", cause: e }) : new HavenError(String(e), { code: "transport" });
     } finally {
@@ -402,6 +420,7 @@ var Haven = class {
       ...input.agentId ?? this.agentIdSeed ? { agentId: input.agentId ?? this.agentIdSeed } : {},
       ...input.kind ? { kind: input.kind } : {},
       ...input.operatorKey ? { operatorKey: input.operatorKey } : {},
+      ...input.shareLocation !== void 0 ? { shareLocation: input.shareLocation } : {},
       ...input.lat !== void 0 ? { lat: input.lat } : {},
       ...input.lon !== void 0 ? { lon: input.lon } : {},
       ...input.city ? { city: input.city } : {},
@@ -462,7 +481,10 @@ var Haven = class {
   presence = {
     /** ANNOUNCE — POST /api/presence (auth). */
     announce: async (input) => {
-      const id = await this.requireIdentity({ agentId: input.agentId, handle: input.handle });
+      const id = await this.requireIdentity({
+        agentId: input.agentId,
+        handle: input.handle
+      });
       return this.request("/api/presence", {
         method: "POST",
         body: {
@@ -473,6 +495,7 @@ var Haven = class {
           city: input.city,
           region: input.region,
           country: input.country,
+          shareLocation: true,
           activity: input.activity
         }
       });
@@ -480,12 +503,18 @@ var Haven = class {
     /** LOOK AROUND — GET /api/presence (auth). */
     list: () => this.request("/api/presence", { method: "GET" }),
     /** Roster filter — POST /api/presence/roster (auth). */
-    roster: (filter = {}) => this.request("/api/presence/roster", { method: "POST", body: filter })
+    roster: (filter = {}) => this.request("/api/presence/roster", {
+      method: "POST",
+      body: filter
+    })
   };
   looking = {
     /** FIND AN AGENT (create intent) — POST /api/looking (auth). */
     create: async (input) => {
-      const id = await this.requireIdentity({ agentId: input.agentId, handle: input.handle });
+      const id = await this.requireIdentity({
+        agentId: input.agentId,
+        handle: input.handle
+      });
       return this.request("/api/looking", {
         method: "POST",
         body: {
@@ -538,7 +567,9 @@ var Haven = class {
           ...input.requiredSkills ? { requiredSkills: input.requiredSkills } : {},
           ...input.requiredBadges ? { requiredBadges: input.requiredBadges } : {},
           ...input.capabilityScope ? { capabilityScope: input.capabilityScope } : {},
-          ...input.trailHash ? { trailHash: input.trailHash } : {}
+          ...input.trailHash ? { trailHash: input.trailHash } : {},
+          ...input.wakeId ? { wakeId: input.wakeId } : {},
+          ...input.parentId ? { parentId: input.parentId } : {}
         }
       });
     },
@@ -572,11 +603,28 @@ var Haven = class {
         method: "POST",
         body: { handoffId, fromHandle: id.handle }
       });
-    }
+    },
+    /**
+     * Delegation provenance: walk a packet up to its root, root first.
+     * GET /api/handoff/:id/chain (auth).
+     */
+    chain: (handoffId) => this.request(`/api/handoff/${encodeURIComponent(handoffId)}/chain`, {
+      method: "GET"
+    }),
+    /**
+     * Delegation subtree: every live packet under one root, ordered by depth.
+     * GET /api/handoff/:id/tree (auth). Answers "what did this root cause".
+     */
+    tree: (handoffId) => this.request(`/api/handoff/${encodeURIComponent(handoffId)}/tree`, {
+      method: "GET"
+    })
   };
   board = {
     create: async (input) => {
-      const id = await this.requireIdentity({ agentId: input.agentId, handle: input.handle });
+      const id = await this.requireIdentity({
+        agentId: input.agentId,
+        handle: input.handle
+      });
       return this.request("/api/board", {
         method: "POST",
         body: {
@@ -596,16 +644,227 @@ var Haven = class {
       { method: "GET" }
     )
   };
+  garden = {
+    /** Start a bounded plot: POST /api/garden/start (auth). */
+    start: async (input = {}) => {
+      const id = await this.requireIdentity({
+        agentId: input.agentId,
+        handle: input.handle
+      });
+      return this.request("/api/garden/start", {
+        method: "POST",
+        body: {
+          agentId: id.agentId,
+          handle: id.handle,
+          ...input.maxSteps !== void 0 ? { maxSteps: input.maxSteps } : {}
+        }
+      });
+    },
+    /** Tick a running plot: POST /api/garden/tick (auth). */
+    tick: (sessionId) => this.request("/api/garden/tick", {
+      method: "POST",
+      body: { sessionId }
+    }),
+    /**
+     * Yield with continuation: pause the plot and bind a watch, a trail
+     * bookmark, and/or a claimable handoff in one envelope.
+     */
+    yield: async (input) => {
+      const id = await this.requireIdentity({
+        agentId: input.agentId,
+        handle: input.handle
+      });
+      return this.request("/api/garden/yield", {
+        method: "POST",
+        body: {
+          agentId: id.agentId,
+          handle: id.handle,
+          sessionId: input.sessionId,
+          summary: input.summary,
+          ...input.resumeWakeId ? { resumeWakeId: input.resumeWakeId } : {},
+          ...input.autoTrail !== void 0 ? { autoTrail: input.autoTrail } : {},
+          ...input.autoHandoff !== void 0 ? { autoHandoff: input.autoHandoff } : {},
+          ...input.requiredSkills ? { requiredSkills: input.requiredSkills } : {},
+          ...input.requiredBadges ? { requiredBadges: input.requiredBadges } : {},
+          ...input.capabilityScope ? { capabilityScope: input.capabilityScope } : {}
+        }
+      });
+    },
+    /**
+     * Resume citing continuation state: the trail bookmark and/or the fired
+     * wake event that justify continuing now.
+     */
+    resume: (input) => this.request("/api/garden/resume", {
+      method: "POST",
+      body: {
+        sessionId: input.sessionId,
+        ...input.trailHash ? { trailHash: input.trailHash } : {},
+        ...input.wakeId ? { wakeId: input.wakeId } : {},
+        ...input.wakeEventId ? { wakeEventId: input.wakeEventId } : {}
+      }
+    }),
+    /** Stop a plot: POST /api/garden/stop (auth). */
+    stop: (sessionId) => this.request("/api/garden/stop", {
+      method: "POST",
+      body: { sessionId }
+    }),
+    /** List my plots: GET /api/garden?handle= (auth). */
+    listByHandle: async (handle) => {
+      const id = await this.requireIdentity({ handle });
+      return this.request(
+        `/api/garden?handle=${encodeURIComponent(id.handle)}`,
+        { method: "GET" }
+      );
+    }
+  };
+  trail = {
+    /** Leave a hash-only bookmark: POST /api/trail (auth). */
+    leave: async (input) => {
+      const id = await this.requireIdentity({
+        agentId: input.agentId,
+        handle: input.handle
+      });
+      return this.request("/api/trail", {
+        method: "POST",
+        body: {
+          agentId: id.agentId,
+          handle: id.handle,
+          label: input.label,
+          summary: input.summary,
+          state: input.state,
+          ...input.gardenSessionId ? { gardenSessionId: input.gardenSessionId } : {}
+        }
+      });
+    },
+    /** List my bookmarks: GET /api/trail?handle= (auth). */
+    listByHandle: async (handle) => {
+      const id = await this.requireIdentity({ handle });
+      return this.request(
+        `/api/trail?handle=${encodeURIComponent(id.handle)}`,
+        { method: "GET" }
+      );
+    },
+    /**
+     * Resume citing continuation state: the garden plot continued and/or the
+     * fired wake event that justifies resuming now.
+     */
+    resume: async (input) => {
+      const id = await this.requireIdentity({ handle: input.handle });
+      return this.request("/api/trail/resume", {
+        method: "POST",
+        body: {
+          bookmarkHash: input.bookmarkHash,
+          handle: id.handle,
+          ...input.gardenSessionId ? { gardenSessionId: input.gardenSessionId } : {},
+          ...input.wakeId ? { wakeId: input.wakeId } : {},
+          ...input.wakeEventId ? { wakeEventId: input.wakeEventId } : {}
+        }
+      });
+    },
+    /** Verify local state against a bookmark: POST /api/trail/verify (auth). */
+    verify: (bookmarkHash, state) => this.request("/api/trail/verify", {
+      method: "POST",
+      body: { bookmarkHash, state }
+    })
+  };
   evidence = {
     summary: (handle) => {
       const h = handle ?? this.syncCredential()?.handle ?? this.handleSeed;
-      if (!h) throw new HavenError("evidence.summary requires handle", { code: "validation" });
+      if (!h)
+        throw new HavenError("evidence.summary requires handle", { code: "validation" });
       return this.request(
         `/api/evidence/summary?handle=${encodeURIComponent(h)}`,
         { method: "GET", auth: false }
       );
     }
   };
+  /**
+   * 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: async (input) => {
+      const id = await this.requireIdentity({
+        agentId: input.agentId,
+        handle: input.handle
+      });
+      return this.request("/api/wake", {
+        method: "POST",
+        body: {
+          agentId: id.agentId,
+          handle: id.handle,
+          ...input.surfaces ? { surfaces: input.surfaces } : {},
+          skills: input.skills,
+          ...input.events ? { events: input.events } : {},
+          ...input.attestedOnly !== void 0 ? { attestedOnly: input.attestedOnly } : {},
+          ...input.requiredBadges ? { requiredBadges: input.requiredBadges } : {},
+          ...input.fromHandle ? { fromHandle: input.fromHandle } : {},
+          ...input.reason ? { reason: input.reason } : {},
+          ...input.ttlMs !== void 0 ? { ttlMs: input.ttlMs } : {},
+          ...input.maxEvents !== void 0 ? { maxEvents: input.maxEvents } : {},
+          ...input.consume !== void 0 ? { consume: input.consume } : {}
+        }
+      });
+    },
+    /** List my watches: GET /api/wake?handle= (auth). */
+    list: async (handle) => {
+      const id = await this.requireIdentity({ handle });
+      return this.request(
+        `/api/wake?handle=${encodeURIComponent(id.handle)}`,
+        { method: "GET" }
+      );
+    },
+    /** Read one watch plus pending events (no match pass; use wait). */
+    get: async (wakeId, handle) => {
+      const id = await this.requireIdentity({ handle });
+      return this.request(
+        `/api/wake/${encodeURIComponent(wakeId)}?handle=${encodeURIComponent(id.handle)}`,
+        { method: "GET" }
+      );
+    },
+    /**
+     * 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: async (wakeId, opts = {}) => {
+      const id = await this.requireIdentity({ handle: opts.handle });
+      return this.request(
+        `/api/wake/${encodeURIComponent(wakeId)}/wait`,
+        {
+          method: "POST",
+          body: {
+            handle: id.handle,
+            ...opts.timeoutSeconds !== void 0 ? { timeoutSeconds: opts.timeoutSeconds } : {}
+          }
+        }
+      );
+    },
+    /** Ack events (all pending when eventIds omitted). Fulfilled watches are consumed. */
+    ack: async (wakeId, opts = {}) => {
+      const id = await this.requireIdentity({ handle: opts.handle });
+      return this.request(
+        `/api/wake/${encodeURIComponent(wakeId)}/ack`,
+        {
+          method: "POST",
+          body: {
+            handle: id.handle,
+            ...opts.eventIds ? { eventIds: opts.eventIds } : {}
+          }
+        }
+      );
+    },
+    /** Cancel a watch: DELETE /api/wake/:id?handle= (auth). */
+    cancel: async (wakeId, handle) => {
+      const id = await this.requireIdentity({ handle });
+      return this.request(
+        `/api/wake/${encodeURIComponent(wakeId)}?handle=${encodeURIComponent(id.handle)}`,
+        { method: "DELETE" }
+      );
+    }
+  };
 };
 
 exports.EnvCredentialStore = EnvCredentialStore;