@ziggs-ai/api-client 0.6.0 → 0.6.3

package/dist/capabilities/links.d.ts

@@ -7,7 +7,16 @@ import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
  * return it too (they used to leak the raw agreement doc).
  */
 export declare function linkSummary(a: Agreement): Record<string, unknown>;
-/** A link is reach-only — the follow-up move differs by surface tool names. */
+/**
+ * A link is reach-only — the follow-up move differs by surface tool names.
+ *
+ * Opening a chat is itself the admission: the backend issues a standing from-now
+ * chat grant to every agent member as it creates the room, so both delegates can
+ * read and post immediately. Do NOT tell agents to follow chat_open with an
+ * issue_grant on that same new chat — that only mints a duplicate grant carrying
+ * the default 30-day expiry. issue_grant / context_delegate are for scopes that
+ * already exist (an older chat, an agreement, an org).
+ */
 export declare function linkIsReachOnly(env: CapabilityEnv): string;
 export declare const createLinkInviteCapability: CapabilityDefinition;
 export declare const listLinksCapability: CapabilityDefinition;

package/dist/capabilities/links.js

@@ -11,11 +11,34 @@ function webAppOrigin(env) {
  * own assistant, which then connects itself and claims the invite. The claim
  * URL alone only helps someone who already has Ziggs and an assistant wired
  * up, so hand the caller both and let it pick per recipient.
+ *
+ * The account question comes FIRST, and the answer is always the claim URL —
+ * never 'Create account' on the MCP consent screen. Signup is invite-gated and
+ * only the claim URL carries the invite that waives it; the consent screen's
+ * signup button carries nothing, and nothing in an MCP OAuth handshake can
+ * carry it for them (the client builds its authorize request from RFC 8414/9728
+ * discovery, so a query param on the pasted server URL never reaches us). So a
+ * recipient new to Ziggs who lets their assistant lead used to hit a hard 403
+ * with no way back. Ordering is the whole fix: the URL both signs them up AND
+ * claims, leaving the assistant less to do, not more.
+ *
+ * Keep in step with the web app's copy of this text (frontend
+ * src/lib/links/inviteShare.ts) — same instructions, two surfaces.
  */
 function invitePasteText(agreementId, claimUrl) {
     return [
         'Connect me to Ziggs and accept this agent link invite.',
         '',
+        'First ask me: do I already have a Ziggs account?',
+        '',
+        `  If no, or I am not sure — open this in a browser: ${claimUrl}`,
+        '  That creates my account and accepts the link in one step, and needs no',
+        "  invite code. Do NOT send me to 'Create account' on the Ziggs consent",
+        '  screen instead — signup there is gated and will reject me. Once I am',
+        '  back, continue from step 1 to connect yourself; step 2 is already done.',
+        '',
+        '  If yes — start at step 1.',
+        '',
         `1. Add this MCP server: ${ZIGGS_MCP_URL}`,
         '   It speaks Streamable HTTP and uses OAuth — pasting the URL is enough,',
         '   but I may need to approve a consent screen in my browser.',
@@ -24,8 +47,6 @@ function invitePasteText(agreementId, claimUrl) {
         '',
         'If you cannot add MCP servers yourself, tell me exactly where to paste that',
         "URL in my assistant's settings, then continue from step 2.",
-        '',
-        `Invite link (if you need it in a browser instead): ${claimUrl}`,
     ].join('\n');
 }
 /**
@@ -49,11 +70,20 @@ export function linkSummary(a) {
         createdAt: a.createdAt,
     };
 }
-/** A link is reach-only — the follow-up move differs by surface tool names. */
+/**
+ * A link is reach-only — the follow-up move differs by surface tool names.
+ *
+ * Opening a chat is itself the admission: the backend issues a standing from-now
+ * chat grant to every agent member as it creates the room, so both delegates can
+ * read and post immediately. Do NOT tell agents to follow chat_open with an
+ * issue_grant on that same new chat — that only mints a duplicate grant carrying
+ * the default 30-day expiry. issue_grant / context_delegate are for scopes that
+ * already exist (an older chat, an agreement, an org).
+ */
 export function linkIsReachOnly(env) {
     return env.surface === 'mcp'
-        ? 'A link is reach-only. Open a chat with the peer (ziggs_chat_open, participantId = peer agent id) and grant it chat access with ziggs_context_issue_grant, or share a slice of a grant you hold with ziggs_context_delegate, before reading context.'
-        : 'A link is reach-only: it does not grant context. Share a slice of a grant you hold with context_delegate, or ask the peer owner to issue one, before reading.';
+        ? 'A link is reach-only — it shares no context on its own. Open a chat with the peer (ziggs_chat_open, participantId = peer agent id): that admits both delegates to read and post from then on. To share context that already exists, issue a grant on it with ziggs_context_issue_grant or share a slice of one you hold with ziggs_context_delegate.'
+        : 'A link is reach-only — it shares no context on its own. Opening a chat with the peer admits both delegates to it from then on. To share context that already exists, share a slice of a grant you hold with context_delegate, or ask the peer owner to issue one.';
 }
 const LINK_STATUSES = ['active', 'open', 'cancelled', 'all'];
 /**
@@ -106,8 +136,8 @@ export const createLinkInviteCapability = {
             seatsRemaining: seats - (agreement.linkInvite?.claimsUsed ?? 0),
             pasteText: invitePasteText(agreement.agreementId, claimUrl),
             message: env.surface === 'mcp'
-                ? `Open link invite created, ${seatNote}. Give the human BOTH forms and say which is which: claimUrl for a recipient who already uses Ziggs, pasteText for one who has an AI assistant but no Ziggs account — pasting it makes their assistant connect and claim the invite itself. A recipient with no Ziggs account can sign up straight from the link; no beta code needed. No agent id needed on either side.`
-                : `Open link invite created, ${seatNote}. Share claimUrl with a counterparty who already uses Ziggs, or pasteText with one who has an assistant but no Ziggs account yet — their assistant connects and claims it. A recipient with no Ziggs account can sign up straight from the link; no beta code needed. No agent id needed on either side. Revoke with agreement_revoke to disable.`,
+                ? `Open link invite created, ${seatNote}. Give the human BOTH forms and say which is which: claimUrl is the one that always works — a recipient with no Ziggs account signs up straight from it, no beta code needed, and it accepts the link in the same step. pasteText is for a recipient who would rather their own assistant do the wiring; it starts by sending them to claimUrl if they have no account yet, since signup on the MCP consent screen is gated and would reject them. Either way the recipient needs their own assistant connected before the link carries anything. No agent id needed on either side.`
+                : `Open link invite created, ${seatNote}. claimUrl is the one that always works — a recipient with no Ziggs account signs up straight from it, no beta code needed, and it accepts the link in the same step. pasteText is for a recipient whose own assistant does the wiring; it sends them to claimUrl first if they have no account, since signup on the consent screen is gated. Either way they need an assistant connected before the link carries anything. No agent id needed on either side. Revoke with agreement_revoke to disable.`,
             agreement: linkSummary(agreement),
         };
     },

package/dist/http/ArtifactsClient.d.ts

@@ -36,6 +36,22 @@ export interface WriteArtifactInput {
  * writes. `visibility: 'agent-private'` is the new home for agent thoughts —
  * they persist, are searchable, but are not visible to other chat parties.
  */
+/**
+ * ZIG-1032 — turn a runtime lane id into a scope the backend can accept.
+ *
+ * A task with no origin chat runs on the lane `agrn-<agreementId>` (see
+ * AgentHost.laneSessionIdForTask). That is a routing key, not a chat: no such
+ * chat row exists, so passing it as `chatId` made every breadcrumb and recorded
+ * thought on an agreement lane come back 403 "not authorized for this scope" —
+ * a fictional scope reading like an auth failure. The work is agreement-scoped,
+ * so say so; same rule ZIG-924 settled for deliverables.
+ */
+export declare const AGREEMENT_LANE_PREFIX = "agrn-";
+export declare function artifactScopeForSession(sessionId: string): {
+    chatId: string;
+} | {
+    agreementId: string;
+};
 export declare class ArtifactsClient {
     private readonly operatorKey;
     private readonly agentId?;
@@ -54,7 +70,7 @@ export declare class ArtifactsClient {
      * endpoint is updated to accept `visibility`, this falls back to logging
      * locally (operators can still wire their own sink).
      */
-    recordThought(chatId: string, text: string, opts?: {
+    recordThought(sessionId: string, text: string, opts?: {
         idempotencyKey?: string;
     }): Promise<void>;
     write(input: WriteArtifactInput): Promise<void>;

package/dist/http/ArtifactsClient.js

@@ -7,6 +7,23 @@ import { buildOperatorHeaders } from './operatorHeaders.js';
  * writes. `visibility: 'agent-private'` is the new home for agent thoughts —
  * they persist, are searchable, but are not visible to other chat parties.
  */
+/**
+ * ZIG-1032 — turn a runtime lane id into a scope the backend can accept.
+ *
+ * A task with no origin chat runs on the lane `agrn-<agreementId>` (see
+ * AgentHost.laneSessionIdForTask). That is a routing key, not a chat: no such
+ * chat row exists, so passing it as `chatId` made every breadcrumb and recorded
+ * thought on an agreement lane come back 403 "not authorized for this scope" —
+ * a fictional scope reading like an auth failure. The work is agreement-scoped,
+ * so say so; same rule ZIG-924 settled for deliverables.
+ */
+export const AGREEMENT_LANE_PREFIX = 'agrn-';
+export function artifactScopeForSession(sessionId) {
+    if (sessionId.startsWith(AGREEMENT_LANE_PREFIX)) {
+        return { agreementId: sessionId.slice(AGREEMENT_LANE_PREFIX.length) };
+    }
+    return { chatId: sessionId };
+}
 export class ArtifactsClient {
     operatorKey;
     agentId;
@@ -49,9 +66,10 @@ export class ArtifactsClient {
      * endpoint is updated to accept `visibility`, this falls back to logging
      * locally (operators can still wire their own sink).
      */
-    async recordThought(chatId, text, opts = {}) {
+    async recordThought(sessionId, text, opts = {}) {
+        // ZIG-1032: `sessionId` may be an agreement lane, which is not a chat.
         return this.write({
-            chatId,
+            ...artifactScopeForSession(sessionId),
             text,
             content_type: 'thought',
             visibility: 'agent-private',

package/dist/http/InboxClient.d.ts

@@ -28,6 +28,10 @@ export interface InboxProposalRef {
 export interface InboxConnectionRequestRef {
     requestId: string;
     requesterAgentId: string;
+    /** ZIG-1039 — human-readable name for consent cards. */
+    requesterDisplayName?: string | null;
+    /** ZIG-1039 — org label for consent cards. */
+    requesterOrgName?: string | null;
     message: string | null;
     requestedAt: string | null;
 }

package/dist/http/index.d.ts

@@ -5,7 +5,7 @@ export * from './agreementFlows.js';
 export * from './ChatClient.js';
 export { MessagesClient } from './MessagesClient.js';
 export type { ListMessagesOptions, ListMessagesResult } from './MessagesClient.js';
-export { ArtifactsClient } from './ArtifactsClient.js';
+export { ArtifactsClient, artifactScopeForSession, AGREEMENT_LANE_PREFIX, } from './ArtifactsClient.js';
 export type { ArtifactVisibility, ListArtifactsOptions, ListArtifactsQuery, ListArtifactsResult, WriteArtifactInput, } from './ArtifactsClient.js';
 export { ContextReadClient } from './ContextReadClient.js';
 export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, ContextSnapshotResult, } from './ContextReadClient.js';

package/dist/http/index.js

@@ -4,7 +4,9 @@ export * from './MarketplaceClient.js';
 export * from './agreementFlows.js';
 export * from './ChatClient.js';
 export { MessagesClient } from './MessagesClient.js';
-export { ArtifactsClient } from './ArtifactsClient.js';
+export { ArtifactsClient, 
+// ZIG-1032: agreement lanes are not chats — callers scope artifact writes with this.
+artifactScopeForSession, AGREEMENT_LANE_PREFIX, } from './ArtifactsClient.js';
 export { ContextReadClient } from './ContextReadClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export { GrantsClient } from './GrantsClient.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.6.0",
+  "version": "0.6.3",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",