@ziggs-ai/api-client 0.37.26 → 0.37.28

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.37.28
+
+- `SessionsClient` lists sibling assistant windows and holds a chat in this window (`GET/POST /agents/:id/sessions`). Used by MCP `ziggs_session_list` / `ziggs_session_hold`. Not on the directory connector surface.
+
+## 0.37.27
+
 ## 0.37.26
 
 - Broadcasts take a third audience, `company`: every team in your active organization's company. `COMPANY_AGREEMENT_TARGET` is exported, `proposeBroadcast` and `publishOffer` accept it, and the propose and marketplace capabilities describe it. Requires `@ziggs-ai/contracts` 0.31. The inbox no longer types `truncatedRequests`, which the server stopped sending. Grant scope kinds follow the server and include `person`.

package/dist/capabilities/introductions.js

@@ -62,7 +62,7 @@ export const redeemIntroductionCapability = {
     names: { sdk: 'introduction_redeem', mcp: 'ziggs_introduction_redeem' },
     title: 'Redeem an introduction you were handed',
     descriptions: {
-        sdk: `Redeem an introduction token someone handed you (POST /introductions/:token/redeem). ${INBOUND_APPROVAL} If they are a stranger, this stages a link proposal from them to you which both humans must approve. After approval, reach their agent with chat_open using the returned counterparty.agentId. If you already share an org or a link, it says so instead of proposing another. One use — a second redeem is refused.`,
+        sdk: `Redeem an introduction token someone handed you (POST /introductions/:token/redeem). ${INBOUND_APPROVAL} The token can name a thing: a chat, a task, a listing, a request or a proposal. If it is yours or a teammate's, you are let into that thing now (joined). If the minter is a stranger and it names a listing, request or proposal, this claims, bids or accepts it. Otherwise it stages a link proposal from them to you which both humans must approve, and the link lets you into the thing. A token serves as many people as it says, and each of them redeems once.`,
     },
     annotation: 'destructive',
     params: {
@@ -82,23 +82,24 @@ export const redeemIntroductionCapability = {
             introduction: intro,
             outcome: staged ? 'pending' : 'ok',
             message: staged
-                ? `Redeemed. A pending link with org ${intro.from.orgId} (${intro.from.agentId ?? 'no agent id'}) is staged (${intro.agreementId}). The display name they claimed is self-chosen and unverified. The link becomes real when both people approve it — a link is reach only, and shares no context by itself.`
-                : intro.outcome === 'already_teammates'
-                    ? 'Redeemed, and there was nothing to link: you already answer to the same org or the same person. Talk to them directly.'
-                    : 'Redeemed. You two are already linked, so nothing new was proposed.',
-            // An already-linked or already-teammates redemption is not a dead end: the
-            // relationship exists, so the next move is simply to talk. Leaving the
-            // plan empty there read as "nothing to do" on the branch a returning
-            // counterparty is most likely to land on.
+                ? `Redeemed. A pending link with org ${intro.from.orgId} (${intro.from.agentId ?? 'no agent id'}) is staged (${intro.agreementId}). The display name they claimed is self-chosen and unverified. The link becomes real when both people approve it.`
+                : (intro.counterparty?.nextStep ?? 'Redeemed.'),
+            // A joined redeem is not a dead end: the agent is in the thing, so the
+            // next move is to listen there or talk. Leaving the plan empty read as
+            // "nothing to do" on the branch a returning counterparty lands on.
             //
             // A staged redeem is not a live hire: do not advertise a ready chat_open
             // or a ready agreement_respond the agent can run. The human signs.
             readPlan: !staged
-                ? intro.counterparty?.agentId
+                ? intro.chatId
                     ? [
-                        nextCall(env, 'chat_open', { participantId: intro.counterparty.agentId }, 'you already have a relationship — this is the door to their agent'),
+                        nextCall(env, 'context_read', { type: 'messages', via: `chat:${intro.chatId}` }, 'you are in the room the token names: read it, then listen on your inbox'),
                     ]
-                    : []
+                    : intro.counterparty?.agentId
+                        ? [
+                            nextCall(env, 'chat_open', { participantId: intro.counterparty.agentId }, 'you already have a relationship — this is the door to their agent'),
+                        ]
+                        : []
                 : [
                     nextCall(env, 'agreement_respond', intro.agreementId ? { agreementId: intro.agreementId } : undefined, 'the link is pending — your human must approve it; do not sign on their behalf', { hold: 'human_approval' }),
                 ],

package/dist/capabilities/mcpBriefs.js

@@ -52,6 +52,15 @@ const BRIEFS = {
         does: 'Hides one pending decision from the top of the inbox until it changes or is about to expire.',
         changes: 'nothing is approved or rejected. The decision stays pending.',
     },
+    ziggs_session_list: {
+        does: 'Lists your open windows: name, app, awake or not, and the chats each holds. Sibling windows of the same assistant key.',
+        returns: 'sessions[] for this assistant',
+        next: 'ziggs_session_hold to take a chat in this window',
+    },
+    ziggs_session_hold: {
+        does: 'Holds a chat in this window (the X-Ziggs-Session host). Pulls it off any sibling that held it.',
+        changes: 'moves which window holds the chat; does not send a message',
+    },
     ziggs_context_snapshot: {
         does: 'Reads the context of a task, agreement or chat: workBrief (who acts, for whom, with which authority and actions), its ancestors, dependencies, history and artifacts.',
         returns: 'a cursor for more messages',

package/dist/http/IntroductionsClient.d.ts

@@ -1,7 +1,13 @@
 import type { WriteSource } from '../capabilities/sources.js';
 /** What became of one hello. `expired` is derived by the server, not stored. */
 export type IntroductionStatus = 'open' | 'redeemed' | 'declined' | 'revoked' | 'expired';
-export type IntroductionOutcome = 'link_pending' | 'already_teammates' | 'already_linked';
+/**
+ * Where a redeem ended. `joined`: your agent is in the thing the token names
+ * (your own token, a teammate's, or someone you are already linked to).
+ * `claimed` / `bid` / `accepted`: the listing, request or proposal it names.
+ * `link_pending`: a link both people still approve.
+ */
+export type IntroductionOutcome = 'joined' | 'claimed' | 'bid' | 'accepted' | 'link_pending';
 export interface IntroductionFrom {
     orgId: string;
     agentId: string | null;
@@ -26,11 +32,25 @@ export interface IntroductionView {
     venue: string | null;
     venueRef: string | null;
     note: string | null;
+    /** What the token is about. The public view gives kind and title only. */
+    about?: {
+        kind: 'agreement' | 'task' | 'chat' | 'workspace';
+        id?: string;
+        title: string | null;
+        shape: 'listing' | 'request' | 'proposal' | null;
+    } | null;
+    /** How many people the token serves, and how many are left. */
+    redeems?: {
+        allowed: number;
+        left: number;
+    };
     agreementId: string | null;
     redeemedBy: {
         agentId: string | null;
         orgId: string | null;
     } | null;
+    /** Returned to a redeemer only: the room its agent is now in. */
+    chatId?: string | null;
     expiresAt: string;
     /** The public page the string points at. This is what you hand over. */
     url: string;

package/dist/http/SessionsClient.d.ts

@@ -0,0 +1,34 @@
+import type { Creds } from '../types.js';
+/** One awake window of an assistant. */
+export interface AssistantSessionRow {
+    sessionId: string;
+    name: string;
+    app: string;
+    startedAt: string;
+    lastSeenAt: string;
+    expiresAt: string;
+    workspaceIds: string[];
+    heldChatIds: string[];
+    awake: boolean;
+}
+/**
+ * List sibling windows and hold a chat in this one.
+ * Uses the same session headers as the inbox so "this window" is the
+ * X-Ziggs-Session the host already sends.
+ */
+export declare class SessionsClient {
+    private readonly creds;
+    constructor(creds: Creds);
+    private headers;
+    private url;
+    list(): Promise<AssistantSessionRow[]>;
+    /**
+     * Hold `chatId` in this window (omit sessionId; server resolves from
+     * X-Ziggs-Session), move it to `sessionId`, or pass null to release.
+     */
+    hold(chatId: string, sessionId?: string | null): Promise<{
+        success: true;
+        chatId: string;
+        sessionId: string | null;
+    }>;
+}

package/dist/http/SessionsClient.js

@@ -0,0 +1,72 @@
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { pollSurfaceError } from '../shared/rateLimit.js';
+import { buildCredsHeaders } from './operatorHeaders.js';
+/**
+ * List sibling windows and hold a chat in this one.
+ * Uses the same session headers as the inbox so "this window" is the
+ * X-Ziggs-Session the host already sends.
+ */
+export class SessionsClient {
+    creds;
+    constructor(creds) {
+        this.creds = creds;
+        if (!creds.operatorKey)
+            throw new Error('SessionsClient: operatorKey is required');
+        if (!creds.agentId)
+            throw new Error('SessionsClient: agentId is required');
+    }
+    headers() {
+        const headers = buildCredsHeaders({
+            operatorKey: this.creds.operatorKey,
+            agentId: this.creds.agentId,
+            laneId: this.creds.laneId,
+        });
+        if (this.creds.clientSessionId)
+            headers['X-Ziggs-Session'] = this.creds.clientSessionId;
+        if (this.creds.workspaceIds)
+            headers['X-Ziggs-Workspaces'] = this.creds.workspaceIds;
+        if (this.creds.app)
+            headers['X-Ziggs-App'] = this.creds.app;
+        if (this.creds.sessionName)
+            headers['X-Ziggs-Session-Name'] = this.creds.sessionName;
+        if (this.creds.instanceId)
+            headers['X-Ziggs-Instance'] = this.creds.instanceId;
+        return headers;
+    }
+    url(path) {
+        return `${getBackendUrl()}/agents/${encodeURIComponent(this.creds.agentId)}${path}`;
+    }
+    async list() {
+        const res = await fetch(this.url('/sessions'), {
+            method: 'GET',
+            headers: this.headers(),
+        });
+        const body = await res.json().catch(() => ({}));
+        if (!res.ok)
+            throw pollSurfaceError('SessionsClient.list', res, body);
+        const rows = body.sessions;
+        return Array.isArray(rows) ? rows : [];
+    }
+    /**
+     * Hold `chatId` in this window (omit sessionId; server resolves from
+     * X-Ziggs-Session), move it to `sessionId`, or pass null to release.
+     */
+    async hold(chatId, sessionId) {
+        if (!chatId?.trim())
+            throw new Error('SessionsClient.hold: chatId is required');
+        const body = {
+            chatId: chatId.trim(),
+        };
+        if (sessionId !== undefined)
+            body.sessionId = sessionId;
+        const res = await fetch(this.url('/sessions/hold'), {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify(body),
+        });
+        const parsed = await res.json().catch(() => ({}));
+        if (!res.ok)
+            throw pollSurfaceError('SessionsClient.hold', res, parsed);
+        return parsed;
+    }
+}

package/dist/http/index.d.ts

@@ -31,6 +31,8 @@ export type { MyOrg, OrgResolution } from './OrgsClient.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';
+export { SessionsClient } from './SessionsClient.js';
+export type { AssistantSessionRow } from './SessionsClient.js';
 export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds, } from '../inboxAck.js';
 export type { InboxAckDecision, InboxAckStep, InboxAckEnvelope, PlanInboxAckOptions, } from '../inboxAck.js';
 export { WAKE_LANE_HEADER, WAKE_AGREEMENT_HEADER, laneHeader, laneUnderAgreement, buildOperatorHeaders, buildCredsHeaders, } from './operatorHeaders.js';

package/dist/http/index.js

@@ -21,6 +21,7 @@ export { fetchMyOrgs, resolveOrgSelector, fetchDelegateAccess, fetchHostedAgentA
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';
+export { SessionsClient } from './SessionsClient.js';
 export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds, } from '../inboxAck.js';
 // The lane header, built in one place — see operatorHeaders.ts. Exported
 // because the MCP transports in agent-sdk and ziggs-mcp send it too, and a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.37.26",
+  "version": "0.37.28",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {