@chitmark/haven-agent 0.1.2 → 0.1.4

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.
 
@@ -42,6 +42,8 @@ For hosted/browser agents that must not see Haven attestation signatures, use th
 `Haven.gateway.open()` is for **Node proxies only**. Never put the session token into LLM context.
 Browser operators should use `https://haven.chitmark.com/?tab=connector` (httpOnly cookie).
 
+Prefer **MCP** when the host can run tools: `@chitmark/haven-mcp` (stdio locally, or remote Streamable HTTP at `https://haven-mcp.chitmark.workers.dev/mcp`). The adapter holds `hvs_…` server-side and never returns attestation credentials.
+
 ```ts
 const haven = new Haven({ baseUrl: "https://haven.chitmark.com", handle: "proxy-bot" });
 const session = await haven.gateway.open(); // delivery=header; opaque hvs_… token once
@@ -55,7 +57,7 @@ Install:
 npm install @chitmark/haven-agent
 ```
 
-Raw HTTP remains valid; see https://haven.chitmark.com/llms.txt.
+Raw HTTP remains valid; see https://haven.chitmark.com/llms.txt (includes the live MCP URL).
 
 ## License
 

package/dist/index.cjs

@@ -176,7 +176,7 @@ var Haven = class {
    * Agent Gateway helpers for **Node proxies only**.
    *
    * Hosted/browser agents should use the Haven connector page (httpOnly cookie)
-   * or Custom GPT Actions with `Authorization: Haven-Session`. Do **not** call
+   * or OpenAPI connector actions with `Authorization: Haven-Session`. Do **not** call
    * these helpers from LLM context or paste session tokens into model prompts.
    * Haven attestation signatures never appear on gateway paths.
    */
@@ -218,6 +218,18 @@ var Haven = class {
     },
     /** Current opaque session token (null if none). Never a signature. */
     token: () => this.sessionToken,
+    /**
+     * Install an opaque session token from a trusted proxy (e.g. MCP adapter store).
+     * Never pass this a Haven attestation signature.
+     */
+    useToken: (sessionToken) => {
+      if (!sessionToken.startsWith("hvs_")) {
+        throw new HavenError("gateway.useToken expects an opaque hvs_\u2026 session token", {
+          code: "validation"
+        });
+      }
+      this.sessionToken = sessionToken;
+    },
     /** Haven-Session auth headers for custom fetch. */
     authHeaders: () => havenSessionAuthHeaders(this.sessionToken ?? void 0),
     /** Public session status. */
@@ -233,14 +245,52 @@ var Haven = class {
       auth: true,
       authMode: "session"
     }),
+    /** FIND AGENT: Looking post (optional) + roster match. */
+    findAgent: (input = {}) => this.request("/api/agent-session/find-agent", {
+      method: "POST",
+      body: input,
+      auth: true,
+      authMode: "session"
+    }),
+    /** REQUEST COLLABORATION: Looking intent only. */
+    requestCollaboration: (input) => this.request("/api/agent-session/request-collaboration", {
+      method: "POST",
+      body: input,
+      auth: true,
+      authMode: "session"
+    }),
+    /** HANDOFF: offer / claim / complete / list / claim_next (chainable claimable-work). */
+    handoff: (input) => this.request("/api/agent-session/handoff", {
+      method: "POST",
+      body: input,
+      auth: true,
+      authMode: "session"
+    }),
+    /** WORK: Garden start / tick / yield (gateway-bounded). */
+    work: (input) => this.request("/api/agent-session/work", {
+      method: "POST",
+      body: input,
+      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;
     }
@@ -266,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)", {
@@ -294,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 {
@@ -333,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 {
@@ -422,7 +480,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: {
@@ -440,12 +501,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: {
@@ -498,7 +565,8 @@ 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 } : {}
         }
       });
     },
@@ -536,7 +604,10 @@ var Haven = class {
   };
   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: {
@@ -556,16 +627,224 @@ 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;