@ziggs-ai/agent-sdk 0.1.10 → 0.1.12

package/src/agent/hostedAgentConnection.ts

@@ -0,0 +1,41 @@
+/**
+ * Hosted fleet agents connect via api-client (AgentHost), never inbound ziggs-mcp.
+ * @see ZIG-781
+ */
+
+export type McpServerSpec = {
+  type?: string;
+  command?: string;
+  args?: string[];
+};
+
+export function looksLikeInboundZiggsMcp(command: string, args: string[] = []): boolean {
+  const joined = `${command} ${args.join(' ')}`;
+  return /ziggs-mcp|@ziggs-ai\/ziggs-mcp/i.test(joined);
+}
+
+/**
+ * Reject wiring a hosted agent to the inbound Ziggs MCP stdio surface.
+ * Claude SDK agents must use in-process ToolManager tools (createSdkMcpServer).
+ */
+export function assertHostedAgentZiggsTools(
+  mcpServers: Record<string, McpServerSpec | unknown> | undefined,
+): void {
+  if (!mcpServers) return;
+  for (const [name, raw] of Object.entries(mcpServers)) {
+    if (!raw || typeof raw !== 'object') continue;
+    const spec = raw as McpServerSpec;
+    if (spec.type === 'stdio') {
+      throw new Error(
+        `Hosted Ziggs agents must not use stdio MCP (server "${name}"). ` +
+          'Connect via api-client / AgentHost in-process tools.',
+      );
+    }
+    if (looksLikeInboundZiggsMcp(String(spec.command ?? ''), spec.args ?? [])) {
+      throw new Error(
+        `Hosted Ziggs agents must not spawn ziggs-mcp (inbound MCP server "${name}"). ` +
+          'Use AgentHost + in-process tools.',
+      );
+    }
+  }
+}

package/src/agent/toolManagerToSdkMcp.ts

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+import { createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';
+import type { SdkMcpToolDefinition } from '@anthropic-ai/claude-agent-sdk';
+import type { ToolDefinition } from '../tools/defineTool.js';
+import type { ClaudeSdkToolContext } from './claudeSdkTools.js';
+
+type JsonSchema = Record<string, unknown>;
+
+type CallToolResult = {
+  content: Array<{ type: 'text'; text: string }>;
+  isError?: boolean;
+};
+
+function jsonTypeToZod(field: JsonSchema): z.ZodTypeAny {
+  const t = field['type'];
+  if (t === 'string') {
+    let s: z.ZodTypeAny = z.string();
+    if (Array.isArray(field['enum'])) {
+      const vals = field['enum'] as string[];
+      if (vals.length > 0) s = z.enum(vals as [string, ...string[]]);
+    }
+    if (typeof field['description'] === 'string') s = s.describe(field['description']);
+    return s;
+  }
+  if (t === 'number' || t === 'integer') {
+    let n: z.ZodTypeAny = z.number();
+    if (typeof field['description'] === 'string') n = n.describe(field['description']);
+    return n;
+  }
+  if (t === 'boolean') return z.boolean();
+  if (t === 'array') {
+    const items = (field['items'] as JsonSchema | undefined) ?? { type: 'string' };
+    return z.array(jsonTypeToZod(items));
+  }
+  if (t === 'object') {
+    const props = (field['properties'] as Record<string, JsonSchema> | undefined) ?? {};
+    const required = new Set((field['required'] as string[] | undefined) ?? []);
+    const shape: Record<string, z.ZodTypeAny> = {};
+    for (const [key, val] of Object.entries(props)) {
+      let node = jsonTypeToZod(val);
+      if (!required.has(key)) node = node.optional();
+      shape[key] = node;
+    }
+    return z.object(shape).passthrough();
+  }
+  return z.unknown();
+}
+
+function parametersToZodShape(parameters: JsonSchema | undefined): z.ZodRawShape {
+  if (!parameters || parameters['type'] !== 'object') return {};
+  const props = (parameters['properties'] as Record<string, JsonSchema> | undefined) ?? {};
+  const required = new Set((parameters['required'] as string[] | undefined) ?? []);
+  const shape: Record<string, z.ZodTypeAny> = {};
+  for (const [key, val] of Object.entries(props)) {
+    let node = jsonTypeToZod(val);
+    if (!required.has(key)) node = node.optional();
+    shape[key] = node;
+  }
+  return shape;
+}
+
+function toCallToolResult(value: unknown): CallToolResult {
+  const text = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+  return { content: [{ type: 'text', text }] };
+}
+
+function toCallToolError(err: unknown): CallToolResult {
+  const message = err instanceof Error ? err.message : String(err);
+  return { content: [{ type: 'text', text: message }], isError: true };
+}
+
+/**
+ * Map Ziggs `ToolDefinition`s to Claude Agent SDK MCP tools. Each handler routes
+ * execution through `eff({ kind: 'tool-call' })` — the shared executor (ZIG-775).
+ */
+export function buildSdkToolDefs(
+  toolDefs: ToolDefinition[],
+  getContext: () => ClaudeSdkToolContext,
+): Array<SdkMcpToolDefinition> {
+  return toolDefs.map((def) => {
+    const fn = def.schema.function;
+    const name = String(fn['name'] ?? '');
+    const description = String(fn['description'] ?? name);
+    const shape = parametersToZodShape(fn['parameters'] as JsonSchema | undefined);
+    const inputSchema = Object.keys(shape).length > 0
+      ? shape
+      : { _: z.record(z.string(), z.unknown()).optional() };
+
+    return {
+      name,
+      description,
+      inputSchema,
+      _meta: { 'anthropic/alwaysLoad': true },
+      handler: async (args: Record<string, unknown>) => {
+        try {
+          const ctx = getContext();
+          const payload = args._ != null && Object.keys(args).length === 1
+            ? (args._ as Record<string, unknown>)
+            : args;
+          const eff = ctx.eff;
+          if (!eff) return toCallToolError(`tool "${name}": missing eff in tool context`);
+          const sessionId = ctx.chatId ?? ctx.sessionId;
+          if (!sessionId) return toCallToolError(`tool "${name}": missing sessionId in tool context`);
+          const r = await eff({
+            kind: 'tool-call',
+            sessionId,
+            name,
+            args: payload ?? {},
+            senderId: ctx.senderId,
+            senderType: ctx.senderType,
+            onBehalfOfAgreementId: ctx.onBehalfOfAgreementId as string | undefined,
+            runId: ctx.runId,
+          });
+          if (r.ok) return toCallToolResult(r.result);
+          return toCallToolError(r.error ?? `tool "${name}" failed`);
+        } catch (err) {
+          return toCallToolError(err);
+        }
+      },
+    };
+  });
+}
+
+export function buildZiggsSdkMcpServer(
+  toolDefs: ToolDefinition[],
+  getContext: () => ClaudeSdkToolContext,
+  options: { name?: string; instructions?: string } = {},
+) {
+  return createSdkMcpServer({
+    name: options.name ?? 'ziggs',
+    version: '1.0.0',
+    instructions: options.instructions,
+    tools: buildSdkToolDefs(toolDefs, getContext),
+    alwaysLoad: true,
+  });
+}

package/src/defineAgent.ts

@@ -1,12 +1,18 @@
 import type { AgentConfig, DefineAgentInput, Workflow } from './types.js';
 import { validateWorkflow } from './runtime/validateWorkflow.js';
+import { injectKickoffDefault } from './runtime/kickoff.js';
+import { deriveRespondsToProposals } from './runtime/deriveRespondsToProposals.js';
 import { runtimeLog } from './shared/runtimeLog.js';
+import { DEFAULT_MODEL } from './AgentHost.js';
 
 /**
  * Validates the workflow synchronously, resolves merged tools and model, and
- * returns a frozen AgentConfig. Does NOT mutate the input — `wait` action and
- * `activeWait` transitions are the workflow author's responsibility (visible
- * spread of `thinkingDefaults`).
+ * returns a frozen AgentConfig. Never mutates the input. `wait` defaults remain
+ * the author's visible spread of `thinkingDefaults`. ONE default is injected (as
+ * new objects): the agreement-kickoff state `kickingOff` plus a last-position
+ * transition into it, appended to every state that does not already handle a
+ * proposer-side proposal-resolved/approve outcome (runtime/kickoff.ts). The
+ * state name 'kickingOff' is reserved; defining it throws.
  *
  * Validation throws WorkflowValidationError on hard problems and logs warnings
  * on soft ones (e.g. missing wait fallthrough).
@@ -17,12 +23,14 @@ export function defineAgent(input: DefineAgentInput): AgentConfig {
   if (!input?.states) throw new Error('[defineAgent] states is required');
   if (!input?.initial) throw new Error('[defineAgent] initial state is required');
 
-  const workflow: Workflow = {
+  // Agreement-kickoff default (see runtime/kickoff.ts): injected BEFORE
+  // validation so the injected state/transitions are validated too.
+  const workflow: Workflow = injectKickoffDefault({
     id: input.agentId,
     description: input.description,
     initial: input.initial,
     states: input.states,
-  };
+  });
 
   const { warnings } = validateWorkflow(workflow);
   for (const w of warnings) runtimeLog.warn('defineAgent', w);
@@ -32,10 +40,14 @@ export function defineAgent(input: DefineAgentInput): AgentConfig {
     ...(Array.isArray(input.services?.tools) ? input.services!.tools! : []),
   ];
 
+  // Model resolution, most-specific-first: a per-agent pin, then the
+  // fleet-wide `LLM_MODEL` lever, then the single `DEFAULT_MODEL` fallback (the
+  // ONE place the default lives — see AgentHost). The id also picks the provider
+  // (claude-* → Anthropic). No agent hardcodes its own fallback.
   const model =
     input.services?.llm?.model ||
-    process.env.OPENAI_MODEL ||
-    'gpt-5.4';
+    process.env.LLM_MODEL ||
+    DEFAULT_MODEL;
 
   // Strip the structural fields we already consumed; pass through everything
   // else (operatorKey, taskTools, custom keys consumed by AgentHost).
@@ -46,6 +58,7 @@ export function defineAgent(input: DefineAgentInput): AgentConfig {
 
   const config: AgentConfig = {
     openaiKey: process.env.OPENAI_API_KEY,
+    anthropicKey: process.env.ANTHROPIC_API_KEY,
     ...(operatorKey ? { operatorKey } : {}),
     agentId,
     description,
@@ -53,6 +66,8 @@ export function defineAgent(input: DefineAgentInput): AgentConfig {
     tools,
     model,
     workflow,
+    respondsToProposals:
+      input.respondsToProposals ?? deriveRespondsToProposals(workflow),
     ...(input.services ? { services: input.services } : {}),
     ...(taskTools !== undefined ? { taskTools } : {}),
     ...rest,

package/src/index.ts

@@ -3,7 +3,7 @@
  *
  * Foundation:
  *   • Outcome union — discriminated, hybrid (closed core + extension)
- *   • Workflow shape — explicit kind: 'parked' | 'thinking'
+ *   • Workflow shape — explicit kind: 'parked' | 'thinking' | 'mechanical'
  *   • Visible defaults — thinkingDefaults({ initial }) spread by author
  *   • Validation at load — defineAgent throws on hard problems, warns on soft
  */
@@ -11,29 +11,39 @@
 export { defineAgent } from './defineAgent.js';
 export { createMcpAgent, resolveZiggsGatewayTarget, wrapGatewayFetch, ZiggsGatewayError } from './adapters/McpAdapter.js';
 export type { CreateMcpAgentOptions, McpAgentHandle, McpTransportConfig } from './adapters/McpAdapter.js';
-export { AgentHost, createAgent, createAgentPool } from './AgentHost.js';
+export { AgentHost, createAgent, createAgentPool, DEFAULT_MODEL } from './AgentHost.js';
 export { Agent } from './agent/Agent.js';
+export { ClaudeSdkAgent } from './agent/ClaudeSdkAgent.js';
+export type { CognitionKind } from './agent/ClaudeSdkAgent.js';
 export type { TickInput, TickOutput, AgentOptions } from './agent/Agent.js';
 export type { SessionResolver, AgentHostOptions } from './AgentHost.js';
 export { createZiggsEffectHandler } from './server/ZiggsEffectHandler.js';
 export type { ZiggsEffectDeps } from './server/ZiggsEffectHandler.js';
 export { EventQueue } from './server/EventQueue.js';
+export { StateTimers } from './server/StateTimers.js';
+export type { StateTimeoutEvent } from './server/StateTimers.js';
 export { OutboxBuffer } from './server/OutboxBuffer.js';
 export { normalizeIncomingEvent } from './ingress/normalizeIncoming.js';
 
 // Runtime primitives
 export { AgentMachine, type TransitionEvent } from './runtime/AgentMachine.js';
 export { runTurn } from './runtime/runTurn.js';
+export { runMechanical } from './runtime/runMechanical.js';
 export { PromptBuilder } from './runtime/PromptBuilder.js';
-export { thinkingDefaults, defineThinkingState, DEFAULT_WAIT_PROMPT } from './runtime/defaults.js';
+export { thinkingDefaults, defineThinkingState, defineMechanicalState, DEFAULT_WAIT_PROMPT } from './runtime/defaults.js';
+export { KICKOFF_STATE, injectKickoffDefault, buildKickoffState } from './runtime/kickoff.js';
 export { validateWorkflow, WorkflowValidationError } from './runtime/validateWorkflow.js';
+export {
+  deriveRespondsToProposals,
+  statesRespondToProposals,
+} from './runtime/deriveRespondsToProposals.js';
 export { outcomeFromEvent, outcomeFromActionResult, applyOutcomeToCtx } from './runtime/buildOutcome.js';
 
 // Types
 export type {
   Outcome, OutcomeKind,
   Ctx, Identity, HistoryEntry, ToolResultEntry,
-  Workflow, State, ParkedState, ThinkingState,
+  Workflow, State, ParkedState, ThinkingState, MechanicalState,
   Action, Transition, PromptDef, ActionPrompt, Produces, ProducesFn,
   AgreementRef, TaskRef, ProposalRef,
   AgentConfig, DefineAgentInput, ServicesConfig,
@@ -96,7 +106,6 @@ export {
   WebSocketClient,
   MessagesClient,
   ArtifactsClient,
-  ScopeClient,
   AgentSearchClient,
   getBackendUrl,
   getWebSocketUrl,

package/src/pricing/fleetTierByAgentId.gen.ts

@@ -17,6 +17,13 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "shopper-agent": "D",
   "hire-agent": "B",
   "ziggs-docs-agent": "B",
+  "relay-coordinator": "D",
+  "relay-intake-worker": "D",
+  "relay-work-worker": "D",
+  "relay-deliver-worker": "D",
+  "retry-coordinator": "D",
+  "retry-fail-worker": "D",
+  "retry-ok-worker": "D",
   "weather-forecaster": "A",
   "climate-data-analyst": "A",
   "air-quality-monitor": "A",
@@ -25,6 +32,8 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "uv-index-advisor": "A",
   "pollen-tracker": "A",
   "marine-weather-reporter": "A",
+  "us-alerts-monitor": "A",
+  "daylight-tracker": "A",
   "stock-market-analyst": "A",
   "crypto-tracker": "A",
   "forex-monitor": "A",
@@ -40,12 +49,16 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "world-news-briefer": "A",
   "business-news-analyst": "A",
   "reddit-trend-spotter": "A",
+  "tech-news-digest": "A",
+  "news-searcher": "A",
+  "subreddit-pulse": "A",
   "science-news-reporter": "A",
   "sports-score-tracker": "A",
   "breaking-news-alert": "A",
   "wikipedia-researcher": "A",
   "book-finder": "A",
   "dictionary-thesaurus": "A",
+  "wikidata-explorer": "A",
   "trivia-master": "A",
   "poetry-curator": "A",
   "quote-finder": "A",
@@ -75,6 +88,8 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "distance-calculator": "A",
   "place-finder": "A",
   "ip-geolocator": "A",
+  "postal-code-resolver": "A",
+  "brewery-finder": "A",
   "astronomy-photo-curator": "A",
   "mars-rover-explorer": "A",
   "neo-tracker": "A",
@@ -83,9 +98,16 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "exoplanet-explorer": "A",
   "drug-interaction-checker": "A",
   "solar-system-explorer": "A",
+  "species-lookup": "A",
+  "census-analyst": "A",
+  "river-monitor": "A",
+  "fbi-wanted-monitor": "A",
   "github-repo-analyst": "A",
   "github-issue-tracker": "A",
   "github-pr-reviewer": "A",
+  "package-inspector": "A",
+  "service-status-checker": "A",
+  "password-safety-checker": "A",
   "ip-analyst": "A",
   "qr-code-generator": "A",
   "http-debugger": "A",
@@ -117,6 +139,9 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "uuid-generator": "A",
   "hash-calculator": "A",
   "base64-encoder": "A",
+  "card-dealer": "A",
+  "world-clock": "A",
+  "link-unfurler": "A",
   "code-reviewer": "B",
   "bug-finder": "B",
   "refactoring-advisor": "B",
@@ -141,6 +166,30 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "stack-trace-analyzer": "B",
   "commit-message-writer": "B",
   "schema-designer": "B",
+  "name-brainstormer": "B",
+  "term-explainer": "B",
+  "pros-cons-lister": "B",
+  "decision-matrix-builder": "B",
+  "checklist-generator": "B",
+  "config-converter": "B",
+  "csv-to-table": "B",
+  "markup-converter": "B",
+  "case-converter": "B",
+  "color-converter": "B",
+  "timestamp-humanizer": "B",
+  "text-summarizer": "B",
+  "notes-cleaner": "B",
+  "audience-rewriter": "B",
+  "text-reformatter": "B",
+  "json-fixer": "B",
+  "sql-explainer": "B",
+  "regex-writer": "B",
+  "cron-explainer": "B",
+  "curl-converter": "B",
+  "changelog-writer": "B",
+  "stacktrace-explainer": "B",
+  "diff-explainer": "B",
+  "scaffold-generator": "B",
   "copywriter": "B",
   "technical-writer": "B",
   "blog-post-drafter": "B",
@@ -270,6 +319,9 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "feature-prioritizer": "C",
   "threat-model-committee": "C",
   "negotiation-simulator": "C",
+  "trip-desk": "C",
+  "tech-radar-brief": "C",
+  "market-open-brief": "C",
   "aristotle": "B",
   "plato": "B",
   "confucius": "B",
@@ -720,4 +772,4 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "death-studies-scholar": "B"
 } as Record<string, FleetPricingTier>;
 
-export const FLEET_TIER_MAP_SIZE = 713;
+export const FLEET_TIER_MAP_SIZE = 765;