@ziggs-ai/agent-sdk 0.11.0 → 0.11.1

package/dist/tools/ToolManager.js

@@ -1,5 +1,6 @@
 import AjvModule from 'ajv';
 import { ToolProvider } from './ToolProvider.js';
+import { toolName } from './defineTool.js';
 const AjvClass = AjvModule.default ?? AjvModule;
 const ajv = new AjvClass({ allErrors: true, strict: false });
 function makeError(message, type, extra) {
@@ -49,7 +50,7 @@ export class ToolManager extends ToolProvider {
             throw makeError('Tool must have a schema', 'invalid_tool');
         if (typeof tool.handler !== 'function')
             throw makeError('Tool must have a handler function', 'invalid_tool');
-        const name = (tool.schema.function?.['name'] || tool.schema['name']);
+        const name = toolName(tool);
         if (!name)
             throw makeError('Tool schema must have a name', 'invalid_tool');
         this.tools.set(name, tool);

package/dist/tools/defineTool.d.ts

@@ -24,4 +24,11 @@ export interface DefineToolOptions {
     isAgreementCreation?: boolean;
     isGenericFallback?: boolean;
 }
+/**
+ * The name a tool registers under. `defineTool` always writes
+ * `schema.function.name`, but hand-built and capability-adapted schemas have put
+ * it at the top level too, so both are read — in one place, rather than at every
+ * call site that needs to identify a tool.
+ */
+export declare function toolName(tool: ToolDefinition | undefined): string | undefined;
 export declare function defineTool(name: string, params: Record<string, unknown>, handler: (args: Record<string, unknown>, context: Record<string, unknown>) => Promise<unknown>, options?: DefineToolOptions): ToolDefinition;

package/dist/tools/defineTool.js

@@ -43,6 +43,18 @@ function convertObject(fields) {
         result['required'] = required;
     return result;
 }
+/**
+ * The name a tool registers under. `defineTool` always writes
+ * `schema.function.name`, but hand-built and capability-adapted schemas have put
+ * it at the top level too, so both are read — in one place, rather than at every
+ * call site that needs to identify a tool.
+ */
+export function toolName(tool) {
+    const fromFunction = tool?.schema?.function?.['name'];
+    const fromTop = tool?.schema?.['name'];
+    const name = fromFunction ?? fromTop;
+    return typeof name === 'string' && name ? name : undefined;
+}
 export function defineTool(name, params, handler, options = {}) {
     if (!name || typeof name !== 'string')
         throw new Error('defineTool: name is required');

package/dist/tools/needs.d.ts

@@ -0,0 +1,54 @@
+/**
+ * needs.ts — what an agent cannot work without, declared once.
+ *
+ * An agent is otherwise two hand-written lists — instructions and tools — with
+ * nothing checking they agree, so a prompt can promise work the toolset has no
+ * way to do and the mismatch only surfaces on a real hire. A third list to
+ * compare against the other two would drift the same way, so the declaration
+ * DERIVES the tools instead. The author never writes that part of the list, so
+ * the mismatch cannot be written.
+ *
+ * Scope is agents built on this SDK.
+ */
+import { type ToolDefinition } from './defineTool.js';
+/**
+ * A remote MCP server is stored as `provider: 'mcp'` and goes through the
+ * gateway. `connection_proxy` resolves a NAMED connector and refuses it with
+ * "Unknown provider: mcp" — the second wall linear-janitor hit.
+ */
+export declare const MCP_PROVIDER = "mcp";
+/**
+ * One shape for now, the one we have actually hit. A second kind means a case in
+ * {@link toolsForNeed}: a need nothing derives tools from is a need nothing
+ * enforces.
+ */
+export interface ConnectionNeed {
+    /** Provider, e.g. 'mcp' or a named connector like 'github'. */
+    connection: string;
+}
+export type AgentNeed = ConnectionNeed;
+/** Reads a manifest's `needs` field defensively — it crosses a package edge. */
+export declare function normalizeNeeds(input: unknown): AgentNeed[];
+/**
+ * The tools a stated need implies. `connection_list_grants` rides every need
+ * because seeing the grant is half of using it: the janitor's first failure was
+ * an agent that held a Linear grant and had no way to notice.
+ */
+export declare function toolsForNeed(need: AgentNeed): ToolDefinition[];
+/** Deduped by tool name, so overlapping needs (and a hand-listed tool) merge. */
+export declare function toolsForNeeds(needs: AgentNeed[]): ToolDefinition[];
+/** One line naming what is missing, for a refusal a human can act on. */
+export declare function describeNeed(need: AgentNeed): string;
+/**
+ * Which declared needs have no live grant behind them.
+ *
+ * `providers` are the providers of the agent's live connection grants. The label
+ * a grant carries is the provider, sometimes suffixed with the owner's account
+ * ("github — acme/infra"), so the provider is the part before the separator.
+ */
+export declare function unmetNeeds(needs: AgentNeed[], providers: Array<string | null | undefined>): AgentNeed[];
+/**
+ * The refusal itself. Names the missing access and who can fix it, because the
+ * agent cannot: issuing a connection grant is the connection owner's act.
+ */
+export declare function unmetNeedsMessage(unmet: AgentNeed[]): string;

package/dist/tools/needs.js

@@ -0,0 +1,84 @@
+/**
+ * needs.ts — what an agent cannot work without, declared once.
+ *
+ * An agent is otherwise two hand-written lists — instructions and tools — with
+ * nothing checking they agree, so a prompt can promise work the toolset has no
+ * way to do and the mismatch only surfaces on a real hire. A third list to
+ * compare against the other two would drift the same way, so the declaration
+ * DERIVES the tools instead. The author never writes that part of the list, so
+ * the mismatch cannot be written.
+ *
+ * Scope is agents built on this SDK.
+ */
+import { toolName } from './defineTool.js';
+import { connectionListGrantsTool, connectionProxyTool } from '../server/tools/tier2/connectionTools.js';
+import { MCP_CONNECTION_TOOLS } from '../server/tools/tier2/mcpConnectionTools.js';
+/**
+ * A remote MCP server is stored as `provider: 'mcp'` and goes through the
+ * gateway. `connection_proxy` resolves a NAMED connector and refuses it with
+ * "Unknown provider: mcp" — the second wall linear-janitor hit.
+ */
+export const MCP_PROVIDER = 'mcp';
+/** Reads a manifest's `needs` field defensively — it crosses a package edge. */
+export function normalizeNeeds(input) {
+    if (!Array.isArray(input))
+        return [];
+    const out = [];
+    for (const raw of input) {
+        const connection = raw?.connection;
+        if (typeof connection === 'string' && connection.trim()) {
+            out.push({ connection: connection.trim() });
+        }
+    }
+    return out;
+}
+/**
+ * The tools a stated need implies. `connection_list_grants` rides every need
+ * because seeing the grant is half of using it: the janitor's first failure was
+ * an agent that held a Linear grant and had no way to notice.
+ */
+export function toolsForNeed(need) {
+    return need.connection === MCP_PROVIDER
+        ? [connectionListGrantsTool, ...MCP_CONNECTION_TOOLS]
+        : [connectionListGrantsTool, connectionProxyTool];
+}
+/** Deduped by tool name, so overlapping needs (and a hand-listed tool) merge. */
+export function toolsForNeeds(needs) {
+    const byName = new Map();
+    for (const need of needs) {
+        for (const tool of toolsForNeed(need)) {
+            const name = toolName(tool);
+            if (name)
+                byName.set(name, tool);
+        }
+    }
+    return [...byName.values()];
+}
+/** One line naming what is missing, for a refusal a human can act on. */
+export function describeNeed(need) {
+    return need.connection === MCP_PROVIDER
+        ? 'a connection to an MCP server'
+        : `a ${need.connection} connection`;
+}
+/**
+ * Which declared needs have no live grant behind them.
+ *
+ * `providers` are the providers of the agent's live connection grants. The label
+ * a grant carries is the provider, sometimes suffixed with the owner's account
+ * ("github — acme/infra"), so the provider is the part before the separator.
+ */
+export function unmetNeeds(needs, providers) {
+    const held = new Set(providers
+        .map((p) => String(p ?? '').split('—')[0].trim().toLowerCase())
+        .filter(Boolean));
+    return needs.filter((n) => !held.has(n.connection.toLowerCase()));
+}
+/**
+ * The refusal itself. Names the missing access and who can fix it, because the
+ * agent cannot: issuing a connection grant is the connection owner's act.
+ */
+export function unmetNeedsMessage(unmet) {
+    const list = unmet.map(describeNeed).join(', ');
+    return (`Cannot start this task: no live grant for ${list}. ` +
+        'Ask the connection owner to issue one for this agent, then re-assign the task.');
+}

package/dist/types.d.ts

@@ -4,6 +4,7 @@
  * One outcome vocabulary, one ctx shape, one transition signature.
  * Every state — parked or thinking — re-enters with exactly one Outcome.
  */
+import type { AgentNeed } from './tools/needs.js';
 export interface AgreementRef {
     agreementId: string;
     parties?: {
@@ -202,7 +203,7 @@ export interface Ctx {
      * Recent wake timestamps (epoch ms) for this lane (claude-sdk cognition
      * only). Backstop circuit breaker: if a lane wakes faster than any real
      * traffic could drive it, the brain skips the LLM instead of burning the
-     * fleet key on a wake storm.
+     * key on a wake storm.
      */
     recentDeliveries?: number[];
 }
@@ -534,6 +535,13 @@ export interface DefineAgentInput {
     initial: string;
     states: Record<string, State>;
     tools?: unknown[];
+    /**
+     * Access this agent cannot work without. Declaring a need PRODUCES the tools
+     * for it — do not also hand-list them — and makes work that arrives without
+     * the grant fail at task start with the missing thing named, instead of
+     * part-way through a real hire.
+     */
+    needs?: AgentNeed[];
     services?: ServicesConfig;
     operatorKey?: string;
     taskTools?: 'all' | 'none' | string[];
@@ -557,6 +565,8 @@ export interface AgentConfig {
     systemPrompt?: string;
     specialization?: string;
     tools: unknown[];
+    /** Normalized declared needs — see DefineAgentInput.needs. */
+    needs?: AgentNeed[];
     model: string;
     workflow: Workflow;
     services?: ServicesConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.204",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.10.0",
+    "@ziggs-ai/api-client": "0.10.4",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",