@ziggs-ai/api-client 0.3.1 → 0.5.0

package/dist/ConnectionManager.d.ts

@@ -1,6 +1,16 @@
 import { type InboxOperatorAgentEntry } from './http/InboxClient.js';
 type OpenFn = () => Promise<unknown>;
 type CloseFn = (handle: unknown) => Promise<void>;
+export interface StartAgentOptions {
+    /**
+     * Keep this host running until it is stopped explicitly — exempt from the
+     * idle sweep, last choice for LRU eviction. For agents the operator named
+     * (launcher `preStart` / `WAKE_AGENTS`): they were started because someone
+     * decided they must be up, not because work arrived, so "no work for a
+     * while" is not a reason to retire them.
+     */
+    pinned?: boolean;
+}
 export interface ConnectionManagerMeta {
     domain?: string;
     expertise?: string[];
@@ -46,6 +56,7 @@ export declare class ConnectionManager {
     private _active;
     private _meta;
     private _starting;
+    private _pinned;
     private _shouldLazyStart;
     constructor({ maxActive, idleTimeoutMs, control, shouldLazyStart }?: ConnectionManagerOptions);
     register(id: string, openFn: OpenFn, closeFn: CloseFn, meta?: ConnectionManagerMeta): void;
@@ -59,12 +70,13 @@ export declare class ConnectionManager {
      * the loop never exits until `stop()` (nothing to resynchronize).
      */
     private _runOperatorPoll;
-    startAgent(id: string): Promise<unknown>;
+    startAgent(id: string, { pinned }?: StartAgentOptions): Promise<unknown>;
     sleep(id: string): Promise<void>;
     sleepAll(): Promise<void>;
     touch(id: string): void;
     list(): string[];
     listActive(): string[];
+    listPinned(): string[];
     get size(): number;
     query({ domain, expertise, tags }?: QueryFilter): string[];
     getMeta(id: string): ConnectionManagerMeta | undefined;

package/dist/ConnectionManager.js

@@ -16,6 +16,7 @@ export class ConnectionManager {
     _active;
     _meta;
     _starting;
+    _pinned;
     _shouldLazyStart;
     constructor({ maxActive = 50, idleTimeoutMs = 60_000, control, shouldLazyStart } = {}) {
         this.maxActive = maxActive;
@@ -28,6 +29,7 @@ export class ConnectionManager {
         this._active = new Map();
         this._meta = new Map();
         this._starting = new Map();
+        this._pinned = new Set();
     }
     register(id, openFn, closeFn, meta) {
         if (!id)
@@ -68,7 +70,19 @@ export class ConnectionManager {
         let consecutiveErrors = 0;
         while (this._polling) {
             try {
-                const env = await inbox.getOperatorInbox({ waitSeconds: OPERATOR_POLL_WAIT_SECONDS });
+                // Roster scoping (ZIG-965): only agents this manager can actually
+                // start are worth sweeping server-side. Without it a partial launcher
+                // (ONLY_AGENTS) paid for a sweep of the owner's whole seeded fleet.
+                //
+                // Already-running agents are excluded: this loop's only job is
+                // lazy-start, and a running host polls its own inbox. Sending them
+                // made the server answer for agents whose entry we then discarded
+                // below — pure duplicate work, growing with how healthy the fleet is.
+                const startable = [...this._entries.keys()].filter((id) => !this._active.has(id));
+                const env = await inbox.getOperatorInbox({
+                    waitSeconds: OPERATOR_POLL_WAIT_SECONDS,
+                    agents: startable,
+                });
                 consecutiveErrors = 0;
                 for (const entry of env.agents) {
                     const id = entry.agentId;
@@ -92,7 +106,11 @@ export class ConnectionManager {
             }
         }
     }
-    async startAgent(id) {
+    async startAgent(id, { pinned = false } = {}) {
+        // Recorded before any await so a pin is never lost to a concurrent
+        // unpinned start of the same id.
+        if (pinned)
+            this._pinned.add(id);
         const existing = this._active.get(id);
         if (existing) {
             this._resetTimer(id);
@@ -136,6 +154,7 @@ export class ConnectionManager {
     touch(id) { this._resetTimer(id); }
     list() { return [...this._entries.keys()]; }
     listActive() { return [...this._active.keys()]; }
+    listPinned() { return [...this._pinned]; }
     get size() { return this._entries.size; }
     query({ domain, expertise, tags } = {}) {
         const results = [];
@@ -156,6 +175,14 @@ export class ConnectionManager {
         if (!entry)
             return;
         clearTimeout(entry.timer);
+        // A pinned host has no idle timer at all. Empty polls don't count as
+        // activity (only delivered items call touch()), so a pinned agent nobody
+        // talks to would otherwise be swept — and with lazy start unable to keep
+        // up at fleet size, nothing brings it back until the process restarts.
+        if (this._pinned.has(id)) {
+            entry.timer = null;
+            return;
+        }
         entry.timer = setTimeout(() => {
             this.sleep(id).catch(err => runtimeLog.warn('ConnectionManager', `idle sleep("${id}") failed: ${err.message}`));
         }, this.idleTimeoutMs);
@@ -168,13 +195,29 @@ export class ConnectionManager {
         this._scheduleIdle(id);
     }
     async _evictLRU() {
-        let oldest = null;
-        for (const [id, entry] of this._active) {
-            const oldestEntry = oldest ? this._active.get(oldest) : null;
-            if (!oldest || !oldestEntry || entry.lastActive < oldestEntry.lastActive)
-                oldest = id;
+        // Pinned hosts are the last to go: pick the LRU unpinned one, and only
+        // fall back to a pinned one when every active host is pinned. maxActive
+        // stays a hard cap — a pin outranks other agents, not the capacity limit —
+        // but say so, because it means more agents were pinned than can run.
+        const oldestOf = (ids) => {
+            let oldest = null;
+            for (const id of ids) {
+                const entry = this._active.get(id);
+                const oldestEntry = oldest ? this._active.get(oldest) : null;
+                if (!entry)
+                    continue;
+                if (!oldest || !oldestEntry || entry.lastActive < oldestEntry.lastActive)
+                    oldest = id;
+            }
+            return oldest;
+        };
+        const active = [...this._active.keys()];
+        const victim = oldestOf(active.filter(id => !this._pinned.has(id))) ?? oldestOf(active);
+        if (!victim)
+            return;
+        if (this._pinned.has(victim)) {
+            runtimeLog.warn('ConnectionManager', `evicting pinned "${victim}": all ${active.length} active hosts are pinned and maxActive=${this.maxActive} is reached — pin fewer agents or raise maxActive`);
         }
-        if (oldest)
-            await this.sleep(oldest);
+        await this.sleep(victim);
     }
 }

package/dist/capabilities/artifacts.d.ts

@@ -0,0 +1,3 @@
+import { type CapabilityDefinition } from './types.js';
+export declare const recordArtifactCapability: CapabilityDefinition;
+export declare const ARTIFACT_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/artifacts.js

@@ -0,0 +1,94 @@
+import { ArtifactsClient } from '../http/ArtifactsClient.js';
+import { fullCreds } from './types.js';
+/**
+ * ZIG-560 teaching: name the result slot on the success path so an agent finds
+ * the right move unaided — worded in each surface's task grammar (SDK
+ * task_update carries the terminal result; MCP has ziggs_set_task_result).
+ */
+function reportingHint(env, contentType, taskId) {
+    const close = env.surface === 'mcp'
+        ? 'ziggs_set_task_result ({ summary, status, links })'
+        : 'task_update';
+    if (contentType === 'result') {
+        return taskId
+            ? `Recorded as a task-bound result artifact. Close the task by setting its terminal result with ${close}.`
+            : `Recorded as a result artifact, but not bound to a task — pass taskId to bind it, then close the task with ${close}.`;
+    }
+    return `Reporting finished work? Record it with content_type=result bound to the task (taskId), then close the task with ${close} — chat messages are conversation only.`;
+}
+export const recordArtifactCapability = {
+    key: 'record_artifact',
+    names: { sdk: 'record_artifact', mcp: 'ziggs_record_artifact' },
+    descriptions: {
+        sdk: 'Write an artifact to a chat or agreement scope. Set visibility explicitly. For a finished deliverable, set content_type=result and pass taskId to bind it to the task — heavy results belong in artifacts, not chat messages.',
+        mcp: 'Write an artifact to a chat or agreement scope. Set visibility explicitly. ' +
+            'For a finished deliverable, set content_type=result and pass taskId to bind it to the task. ' +
+            'Finished work is the task result — set it with ziggs_set_task_result; never report finished work as a chat message (chat is conversation only).',
+    },
+    annotation: 'write',
+    params: {
+        text: { type: 'string', required: true, description: 'Artifact body' },
+        visibility: {
+            type: 'string',
+            required: true,
+            enum: ['chat', 'agent-private'],
+            description: 'chat = visible to scope parties; agent-private = your eyes only',
+        },
+        chatId: { type: 'string', description: 'Target chat scope' },
+        agreementId: {
+            type: 'string',
+            description: 'Target agreement scope — for a hire deliverable, prefer this. When both chatId and agreementId are passed, agreementId wins.',
+        },
+        taskId: {
+            type: 'string',
+            description: 'Optional task — creates a TaskArtifactLink alongside the primary scope link',
+        },
+        content_type: {
+            type: 'string',
+            description: 'Default text; use result for a finished deliverable',
+        },
+        idempotencyKey: {
+            type: 'string',
+            description: 'Optional dedup key: a redelivered record with the same key no-ops and returns the original artifact. Derive it deterministically (e.g. from the source event + step) — not a random value — so a crash-replay reproduces it.',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const agreementId = args['agreementId'];
+        // Agreement wins when both scopes arrive. Models naturally pass the chat
+        // they are standing in alongside the agreement they deliver under; a hard
+        // xor here failed the deliverable at the last step of a finished task
+        // (ZIG-924 dogfood). The backend still enforces exactly-one — we resolve
+        // the ambiguity at the exposed surface instead of erroring.
+        const chatId = agreementId ? undefined : args['chatId'];
+        if (!chatId && !agreementId) {
+            throw new Error('Pass chatId or agreementId');
+        }
+        const visibility = args['visibility'];
+        if (visibility !== 'chat' && visibility !== 'agent-private') {
+            throw new Error('visibility must be chat or agent-private');
+        }
+        const contentType = args['content_type'];
+        const taskId = args['taskId'];
+        const creds = fullCreds(env);
+        const { artifactId } = await new ArtifactsClient(creds.operatorKey, creds.agentId).writeStrict({
+            text: args['text'],
+            visibility,
+            chatId,
+            agreementId,
+            taskId,
+            content_type: contentType,
+            idempotencyKey: args['idempotencyKey'],
+        });
+        return {
+            ok: true,
+            artifactId,
+            visibility,
+            chatId,
+            agreementId,
+            taskId,
+            reportingHint: reportingHint(env, contentType, taskId),
+        };
+    },
+};
+export const ARTIFACT_CAPABILITIES = [recordArtifactCapability];

package/dist/capabilities/chat.d.ts

@@ -0,0 +1,11 @@
+import { type CapabilityDefinition } from './types.js';
+/**
+ * ZIG-900 — the decided chat surface for agents: open_conversation only.
+ * There is deliberately NO chat-listing tool on the SDK: agents read context
+ * only via held grants (ZIG-425) and chat membership auto-mints a chat grant
+ * (ZIG-428/426), so "what chats can I see" is already answered by list_grants
+ * scopeKind=chat (ZIG-626 rule). MCP keeps its rich session-UX lister
+ * (ziggs_list_chats) for humans in Cursor/Claude.
+ */
+export declare const openConversationCapability: CapabilityDefinition;
+export declare const CHAT_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/chat.js

@@ -0,0 +1,38 @@
+import { openConversation } from '../http/ChatClient.js';
+import { fullCreds } from './types.js';
+/**
+ * ZIG-900 — the decided chat surface for agents: open_conversation only.
+ * There is deliberately NO chat-listing tool on the SDK: agents read context
+ * only via held grants (ZIG-425) and chat membership auto-mints a chat grant
+ * (ZIG-428/426), so "what chats can I see" is already answered by list_grants
+ * scopeKind=chat (ZIG-626 rule). MCP keeps its rich session-UX lister
+ * (ziggs_list_chats) for humans in Cursor/Claude.
+ */
+export const openConversationCapability = {
+    key: 'open_conversation',
+    names: { sdk: 'open_conversation', mcp: 'ziggs_open_conversation' },
+    descriptions: {
+        sdk: 'Open or reuse a chat with a user or agent participant. To reach an agent in ANOTHER org, establish a link first — request_link (if you have its agent id) or create_link_invite (if you do not), approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED. To list chats you can already read, use list_grants scopeKind=chat.',
+        mcp: 'Open or reuse a chat with a user or agent participant. To reach an agent in ANOTHER org, an unpublished delegate must establish a link first — call ziggs_request_link (if you have its agent id) or ziggs_create_link_invite (if you do not) and have it approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED.',
+    },
+    annotation: 'write',
+    params: {
+        participantId: {
+            type: 'string',
+            required: true,
+            description: 'User or agent id to converse with (from agent search — do not guess ids)',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        if (!args['participantId'])
+            throw new Error('participantId is required');
+        const { chatId } = await openConversation(args['participantId'], fullCreds(env));
+        const lister = env.surface === 'mcp' ? 'ziggs_list_grants' : 'list_grants';
+        return {
+            chatId,
+            note: `Conversation is open (or reused). Your membership auto-mints a chat grant, so the chat also appears in ${lister} scopeKind=chat for context reads.`,
+        };
+    },
+};
+export const CHAT_CAPABILITIES = [openConversationCapability];

package/dist/capabilities/connections.d.ts

@@ -0,0 +1,4 @@
+import { type CapabilityDefinition } from './types.js';
+export declare const connectionProxyCapability: CapabilityDefinition;
+export declare const requestConnectionCapability: CapabilityDefinition;
+export declare const CONNECTION_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/connections.js

@@ -0,0 +1,112 @@
+import { ConnectionsClient } from '../http/ConnectionsClient.js';
+import { rethrowWithContext, } from './types.js';
+function client(env) {
+    const { operatorKey, agentId } = env.creds;
+    if (!operatorKey)
+        throw new Error('operatorKey missing from tool context');
+    return new ConnectionsClient(operatorKey, agentId, env.baseUrl);
+}
+export const connectionProxyCapability = {
+    key: 'connection_proxy',
+    names: { sdk: 'connection_proxy', mcp: 'ziggs_connection_proxy' },
+    descriptions: {
+        sdk: "Use a stored connection (a third-party credential, e.g. the owner's GitHub/Jira) without ever seeing the credential. Calls the backend connections proxy with a grant the owner issued to this agent: the proxy enforces the grant, decrypts the token server-side, makes the upstream provider call, and returns the result (token-leak guarded on both sides). Provide connectionId, grantId, the provider action (e.g. repo:read), and an optional action-specific payload. Don't know connectionId/grantId yet? Use list_grants (scopeKind=connection) or connection_list_grants first.",
+        mcp: "Use a stored connection (a third-party credential, e.g. the owner's GitHub/Jira — NOT an agent-to-agent Link, see ziggs_list_links for that) without ever seeing the credential. " +
+            'Calls the backend connections proxy with a grant the owner issued to this agent: the proxy enforces the grant, decrypts the token server-side, makes the upstream provider call, and returns the result (token-leak guarded on both sides). ' +
+            'Provide connectionId, grantId, the provider action (e.g. repo:read), and an optional action-specific payload. ' +
+            "Don't know connectionId/grantId yet? Call ziggs_list_my_connections first.",
+    },
+    annotation: 'write',
+    params: {
+        connectionId: { type: 'string', required: true, description: 'Connection to act on' },
+        grantId: {
+            type: 'string',
+            required: true,
+            description: 'Grant the owner issued to this agent for the connection',
+        },
+        action: { type: 'string', required: true, description: 'Provider action, e.g. repo:read' },
+        payload: { type: 'object', description: 'Action-specific arguments (provider-defined)' },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        if (!args['connectionId'])
+            throw new Error('connectionId is required');
+        if (!args['grantId'])
+            throw new Error('grantId is required');
+        if (!args['action'])
+            throw new Error('action is required');
+        try {
+            const result = await client(env).proxy({
+                connectionId: args['connectionId'],
+                grantId: args['grantId'],
+                action: args['action'],
+                payload: args['payload'],
+            });
+            return { ok: true, action: args['action'], result };
+        }
+        catch (e) {
+            rethrowWithContext(e, 'Connection proxy failed');
+        }
+    },
+};
+export const requestConnectionCapability = {
+    key: 'request_connection',
+    names: { sdk: 'request_connection', mcp: 'ziggs_request_connection' },
+    descriptions: {
+        sdk: 'Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. Opens a connection-consent agreement as an approvable card in the chat you pass — the human approves it there like any other agreement. On approval the server is connected (browser OAuth if needed) and you are granted the tools; use them via connection_proxy.',
+        mcp: 'Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. ' +
+            'Opens a connection-consent agreement as an approvable card in the chat you pass — the human approves it there like any other agreement (there is no MCP tool to approve it, so tell them to approve it in the chat). ' +
+            'On approval the server is connected (browser OAuth if needed) and you are granted the tools; the result shows up in ziggs_list_my_connections for use with ziggs_connection_proxy.',
+    },
+    annotation: 'write',
+    params: {
+        chatId: {
+            type: 'string',
+            required: true,
+            description: 'The chat you are working in — the consent card is opened there',
+        },
+        serverUrl: { type: 'string', required: true, description: 'Remote MCP server URL (https)' },
+        tools: {
+            type: 'array',
+            items: { type: 'string' },
+            required: true,
+            description: "Tool names you want — become the grant's allowed_actions caveats",
+        },
+        reason: { type: 'string', description: 'Plain-language reason shown to the human deciding' },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        if (!args['chatId'])
+            throw new Error('chatId is required');
+        if (!args['serverUrl'])
+            throw new Error('serverUrl is required');
+        const tools = args['tools'];
+        if (!Array.isArray(tools) || tools.length === 0) {
+            throw new Error('tools must be a non-empty array of tool names');
+        }
+        try {
+            const result = await client(env).requestMcpConnection({
+                chatId: args['chatId'],
+                serverUrl: args['serverUrl'],
+                tools: tools,
+                reason: args['reason'],
+            });
+            return {
+                ok: true,
+                ...result,
+                note: env.surface === 'mcp'
+                    ? 'A connection-consent card is now in the chat awaiting your principal. Tell the human now (pull-only MCP has no push) — they approve it right in the chat. ' +
+                        'Once approved, the connection + grant appear in ziggs_list_my_connections for ziggs_connection_proxy.'
+                    : 'A connection-consent card is now in the chat awaiting your principal — they approve it right there (ZIG-798 flow). ' +
+                        'Once approved, the connection + grant appear in list_grants (scopeKind=connection) / connection_list_grants for connection_proxy.',
+            };
+        }
+        catch (e) {
+            rethrowWithContext(e, 'Connection request failed');
+        }
+    },
+};
+export const CONNECTION_CAPABILITIES = [
+    connectionProxyCapability,
+    requestConnectionCapability,
+];

package/dist/capabilities/context.d.ts

@@ -0,0 +1,23 @@
+import { type GrantView } from '../http/grants.js';
+import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
+/**
+ * Human/LLM-readable bounds for a context grant. ZIG-646 folded a context
+ * grant's temporal mode + read watermark into the canonical `caveats` array,
+ * so pull them back out here to keep the `bounds` summary stable.
+ */
+export declare function contextBounds(grant: GrantView): Record<string, unknown>;
+/**
+ * ZIG-941 #6 — org-scoped grants may name the org instead of pasting its
+ * opaque org_... id: exact id or case-insensitive name against the operator's
+ * memberships. Ambiguous names throw with the candidate list rather than
+ * guessing; a name that matched nothing throws with a pointer to the org
+ * lister. An org_... id that is not a membership passes through unchanged —
+ * you may hold a grant on an org you do not belong to, so the server stays
+ * the authority on the id.
+ */
+export declare function resolveOrgScopeId(env: CapabilityEnv, scopeId: string): Promise<string>;
+export declare const contextReadCapability: CapabilityDefinition;
+export declare const contextExpandReachCapability: CapabilityDefinition;
+export declare const contextDiscoverGrantableCapability: CapabilityDefinition;
+export declare const contextDelegateCapability: CapabilityDefinition;
+export declare const CONTEXT_CAPABILITIES: CapabilityDefinition[];