@ziggs-ai/agent-sdk 0.1.3 → 0.1.4

package/src/shared/ids.ts

@@ -0,0 +1,3 @@
+export function generateId(): string {
+  return `${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}

package/src/shared/runtimeLog.ts

@@ -0,0 +1,72 @@
+/**
+ * Process-wide log levels for agentplus runtimes. Default is `info` so FSM /
+ * socket chatter stays quiet unless operators opt in.
+ *
+ * Env (first match wins for the debug shortcut):
+ * - `DEBUG_AGENTPLUS=1` or `AGENTPLUS_DEBUG=1` → threshold `debug`
+ * - `LOG_LEVEL` or `AGENTPLUS_LOG_LEVEL` → `debug` | `info` | `warn` | `error` | `silent`
+ *   (`silent` keeps only `error` output)
+ */
+
+export type RuntimeLogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const SEVERITY: Record<RuntimeLogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+function parseThreshold(): number {
+  if (process.env.DEBUG_AGENTPLUS === '1' || process.env.AGENTPLUS_DEBUG === '1') {
+    return SEVERITY.debug;
+  }
+  const raw = (
+    process.env.LOG_LEVEL ||
+    process.env.AGENTPLUS_LOG_LEVEL ||
+    'info'
+  ).toLowerCase();
+  if (raw === 'silent' || raw === 'none') return SEVERITY.error;
+  if (raw === 'debug' || raw === 'trace') return SEVERITY.debug;
+  if (raw === 'warn') return SEVERITY.warn;
+  if (raw === 'error') return SEVERITY.error;
+  return SEVERITY.info;
+}
+
+let cachedThreshold: number | null = null;
+
+function threshold(): number {
+  if (cachedThreshold === null) cachedThreshold = parseThreshold();
+  return cachedThreshold;
+}
+
+/** Test hook: re-read env after `process.env` mutations. */
+export function resetRuntimeLogLevelCache(): void {
+  cachedThreshold = null;
+}
+
+function shouldEmit(level: RuntimeLogLevel): boolean {
+  return SEVERITY[level] >= threshold();
+}
+
+function fmt(scope: string, msg: string): string {
+  return `[${scope}] ${msg}`;
+}
+
+export const runtimeLog = {
+  debug(scope: string, msg: string, ...rest: unknown[]): void {
+    if (!shouldEmit('debug')) return;
+    console.log(fmt(scope, msg), ...rest);
+  },
+  info(scope: string, msg: string, ...rest: unknown[]): void {
+    if (!shouldEmit('info')) return;
+    console.log(fmt(scope, msg), ...rest);
+  },
+  warn(scope: string, msg: string, ...rest: unknown[]): void {
+    if (!shouldEmit('warn')) return;
+    console.warn(fmt(scope, msg), ...rest);
+  },
+  error(scope: string, msg: string, ...rest: unknown[]): void {
+    console.error(fmt(scope, msg), ...rest);
+  },
+};

package/src/shared/types.ts

@@ -0,0 +1,31 @@
+// Inlined from `@ziggs-ai/api-client` so the pure SDK doesn't depend on the
+// Ziggs HTTP client. Both client and server agree on these string constants
+// because the protocol is the same — they're just two views of one schema.
+export const EntryTypes = {
+  MESSAGE:      'message',
+  NOTIFICATION: 'notification',
+  ARTIFACT:     'artifact',
+  TASK_HISTORY: 'task_history',
+} as const;
+
+export type EntryType = (typeof EntryTypes)[keyof typeof EntryTypes];
+
+export const ContentTypes = {
+  TEXT:        'text',
+  OPERATION:   'operation',
+  CONTEXT:     'context',
+  RESULT:      'result',
+  TASK_UPDATE: 'task_update',
+  THOUGHT:     'thought',
+} as const;
+
+export type ContentType = (typeof ContentTypes)[keyof typeof ContentTypes];
+
+export { TaskState, TERMINAL_STATES, OPEN_AGREEMENT_TARGET } from '../tasks/taskCore.js';
+
+export const ContextProperties = {
+  HISTORY:    'history',
+  AGREEMENTS: 'agreements',
+  AGENTS:     'agents',
+  USERS:      'users',
+} as const;

package/src/tasks/protocolRegistry.ts

@@ -0,0 +1,25 @@
+export const PROTOCOL_TOOL_TO_OPERATION = Object.freeze({
+  agreement_propose:                'agreement-propose',
+  agreement_subcontract:            'agreement-subcontract',
+  agreement_respond:                'agreement-respond',
+  agreement_counter_proposal:       'agreement-counter-proposal',
+  agreement_check_proposal:         'agreement-check-proposal',
+  agreement_revoke:                 'agreement-revoke',
+  task_spawn:                       'task-spawn',
+  task_update:                      'task-update',
+  task_update_plan_step:            'task-update-plan-step',
+} as const);
+
+export type ProtocolToolName = keyof typeof PROTOCOL_TOOL_TO_OPERATION;
+export type ProtocolOperation = (typeof PROTOCOL_TOOL_TO_OPERATION)[ProtocolToolName];
+
+export const PROTOCOL_TOOL_NAMES = Object.freeze(Object.keys(PROTOCOL_TOOL_TO_OPERATION)) as readonly ProtocolToolName[];
+
+export function mapProtocolToolToOperation(toolName: string): ProtocolOperation | null {
+  if (!toolName || typeof toolName !== 'string') return null;
+  return (PROTOCOL_TOOL_TO_OPERATION as Record<string, ProtocolOperation>)[toolName] ?? null;
+}
+
+export function isProtocolToolName(toolName: string): toolName is ProtocolToolName {
+  return mapProtocolToolToOperation(toolName) != null;
+}

package/src/tasks/taskCore.ts

@@ -0,0 +1,139 @@
+/**
+ * Canonical Task definitions — states, state machine, shapes, and helpers.
+ * ⚠️  SYNC: Keep in sync with backend/src/tasks/task-core.ts
+ *           and backend/src/agreements/agreement.schema.ts
+ */
+
+export const TaskState = {
+  PROPOSAL:  'proposal',
+  ACTIVE:    'active',
+  COMPLETED: 'completed',
+  FAILED:    'failed',
+  CANCELLED: 'cancelled',
+} as const;
+
+export type TaskStateValue = (typeof TaskState)[keyof typeof TaskState];
+
+export const TASK_STATES: TaskStateValue[] = ['proposal', 'active', 'completed', 'failed', 'cancelled'];
+export const TERMINAL_STATES: TaskStateValue[] = ['completed', 'failed', 'cancelled'];
+
+export const VALID_TRANSITIONS: Partial<Record<TaskStateValue, TaskStateValue[]>> = {
+  proposal: ['active', 'cancelled'],
+  active:   ['completed', 'failed', 'cancelled'],
+};
+
+export function isTerminal(state: string): boolean {
+  return TERMINAL_STATES.includes(state as TaskStateValue);
+}
+
+export function canTransitionTo(from: string, to: string): boolean {
+  if (isTerminal(from)) return false;
+  const allowed = VALID_TRANSITIONS[from as TaskStateValue];
+  if (!allowed) return false;
+  return allowed.includes(to as TaskStateValue);
+}
+
+export function normalizeState(state: string): string {
+  if (state === 'done') return TaskState.COMPLETED;
+  if (state === 'error') return TaskState.FAILED;
+  return state;
+}
+
+export function isValidState(state: string): boolean {
+  return TASK_STATES.includes(state as TaskStateValue);
+}
+
+// ── Shapes ────────────────────────────────────────────────────────────────────
+
+export interface PlanStep {
+  stepId: string;
+  description?: string;
+  order?: number;
+  status?: 'pending' | 'in_progress' | 'completed' | 'skipped';
+  result?: unknown;
+}
+
+export interface TaskHistoryEntry {
+  changeType: string;
+  [key: string]: unknown;
+}
+
+export interface AgreementParties {
+  creatorId?: string | null;
+  providerId?: string | null;
+  payerId?: string | null;
+  proposedToId?: string | null;
+}
+
+export interface AgreementTerms {
+  price?: number | null;
+  lifecycle?: string | null;
+  expiresAt?: string | null;
+  maxExecutions?: number | null;
+  description?: string | null;
+}
+
+export interface AgreementMoney {
+  price?: number | null;
+  paymentStatus?: string | null;
+}
+
+export interface AgreementProposal {
+  status: 'pending' | 'approved' | 'rejected' | null;
+  respondedBy?: string | null;
+  proposedAt?: string | null;
+  respondedAt?: string | null;
+}
+
+export const HistoryChangeType = {
+  CREATED:           'created',
+  STATE_CHANGED:     'state_changed',
+  PROCESSING_CHANGED: 'processing_changed',
+  PLAN_STEP_CHANGED: 'plan_step_changed',
+  PLAN_RESTRUCTURED: 'plan_restructured',
+  PLAN_ACKNOWLEDGED: 'plan_acknowledged',
+} as const;
+
+export type HistoryChangeTypeValue = (typeof HistoryChangeType)[keyof typeof HistoryChangeType];
+
+export interface Agreement {
+  agreementId: string;
+  taskId?: string | null;
+  rootAgreementId?: string | null;
+  parentAgreementId?: string | null;
+  parties: AgreementParties;
+  terms: AgreementTerms;
+  money: AgreementMoney;
+  proposal: AgreementProposal;
+  status: 'draft' | 'open' | 'active' | 'fulfilled' | 'cancelled' | 'refunded';
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface Task {
+  taskId: string;
+  description: string;
+  agreementId: string;
+  agreement?: Agreement | null;
+  state: TaskStateValue;
+  processing: boolean;
+  deleted: boolean;
+  result?: unknown;
+  errorMessage?: string | null;
+  createdAt: string;
+  updatedAt: string;
+  parentTaskId?: string | null;
+  rootTaskId?: string | null;
+  plan?: { steps?: PlanStep[] };
+  history?: TaskHistoryEntry[];
+}
+
+export interface TaskWithFlags extends Task {
+  creatorIsYou?: boolean;
+  providerIsYou?: boolean;
+  payerIsYou?: boolean;
+  proposedToIsYou?: boolean;
+}
+
+/** ⚠️ SYNC: Keep in sync with backend and api-client */
+export const OPEN_AGREEMENT_TARGET = 'everyone' as const;

package/src/tools/ToolManager.ts

@@ -0,0 +1,95 @@
+import AjvModule from 'ajv';
+import { ToolProvider } from './ToolProvider.js';
+import type { ToolDefinition } from './defineTool.js';
+
+// Ajv ships as CJS; handle both ESM default-import shapes
+type ValidateFn = ((data: unknown) => boolean) & { errors?: unknown[] };
+type AjvInstance = { compile: (schema: object) => ValidateFn; errorsText: (errors: unknown) => string };
+const AjvClass = (AjvModule as unknown as { default?: unknown }).default ?? AjvModule;
+const ajv = new (AjvClass as new (opts: object) => AjvInstance)({ allErrors: true, strict: false });
+
+interface ToolError extends Error {
+  type: string;
+  cause?: unknown;
+  data?: unknown;
+}
+
+function makeError(message: string, type: string, extra?: Partial<ToolError>): ToolError {
+  const err = new Error(message) as ToolError;
+  err.type = type;
+  if (extra) Object.assign(err, extra);
+  return err;
+}
+
+function stripNullish(args: Record<string, unknown>): Record<string, unknown> {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) return args;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(args)) {
+    if (v !== null && v !== undefined) out[k] = v;
+  }
+  return out;
+}
+
+export class ToolManager extends ToolProvider {
+  private tools: Map<string, ToolDefinition>;
+
+  constructor() {
+    super();
+    this.tools = new Map();
+  }
+
+  register(tool: ToolDefinition): string {
+    if (!tool?.schema) 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 as unknown as Record<string, unknown>)['name']) as string;
+    if (!name) throw makeError('Tool schema must have a name', 'invalid_tool');
+    this.tools.set(name, tool);
+    return name;
+  }
+
+  registerAll(tools: ToolDefinition[] = []): void {
+    for (const tool of tools) this.register(tool);
+  }
+
+  async getAvailableTools(): Promise<ToolDefinition[]> {
+    return Array.from(this.tools.values());
+  }
+
+  getTool(name: string): ToolDefinition | null {
+    const normalized = this._normalizeName(name) as string;
+    return this.tools.get(normalized) ?? null;
+  }
+
+  async executeTool(
+    name: string,
+    args: Record<string, unknown> = {},
+    context: Record<string, unknown> = {},
+  ): Promise<unknown> {
+    const normalized = this._normalizeName(name) as string;
+    const tool = this.tools.get(normalized);
+    if (!tool) throw makeError(`Tool not found: ${name}`, 'tool_not_found');
+
+    const cleanedArgs = stripNullish(args);
+    this._validateArgs(tool, cleanedArgs);
+
+    try {
+      return await tool.handler(cleanedArgs, context);
+    } catch (error) {
+      throw makeError(`Tool "${name}" failed: ${(error as Error).message}`, 'tool_error', { cause: error });
+    }
+  }
+
+  private _validateArgs(tool: ToolDefinition, args: Record<string, unknown>): void {
+    const parameters = tool.schema.function?.['parameters'] || (tool.schema as unknown as Record<string, unknown>)['parameters'];
+    if (!parameters) return;
+    const validate = ajv.compile(parameters as object);
+    if (!validate(args)) {
+      const name = tool.schema.function?.['name'];
+      throw makeError(
+        `Invalid args for "${name}": ${ajv.errorsText(validate.errors)}`,
+        'validation_error',
+        { data: { errors: validate.errors } },
+      );
+    }
+  }
+}

package/src/tools/{ToolProvider.js → ToolProvider.ts}

@@ -1,28 +1,18 @@
-/**
- * Base class for tool providers.
- * ToolManager and any custom providers extend this.
- */
 export class ToolProvider {
-  async getAvailableTools() {
+  async getAvailableTools(): Promise<unknown[]> {
     throw new Error('getAvailableTools must be implemented');
   }
-
-  async executeTool(name, args = {}, context = {}) {
+  async executeTool(_name: string, _args?: Record<string, unknown>, _context?: Record<string, unknown>): Promise<unknown> {
     throw new Error('executeTool must be implemented');
   }
-
-  getTool(name) {
+  getTool(_name: string): unknown | null {
     throw new Error('getTool must be implemented');
   }
-
-  _normalizeName(name) {
+  _normalizeName(name: unknown): unknown {
     if (!name || typeof name !== 'string') return name;
-
     const prefixes = ['functions.', 'tools.', 'function.', 'tool.'];
     for (const prefix of prefixes) {
-      if (name.startsWith(prefix)) {
-        return name.substring(prefix.length);
-      }
+      if (name.startsWith(prefix)) return name.substring(prefix.length);
     }
     return name;
   }

package/src/tools/defineTool.ts

@@ -0,0 +1,90 @@
+const PRIMITIVES = new Set(['string', 'number', 'boolean', 'integer']);
+
+type FieldDef = string | unknown[] | Record<string, unknown>;
+
+function convertField(value: FieldDef): { schema: Record<string, unknown>; required: boolean } {
+  if (typeof value === 'string') {
+    if (!PRIMITIVES.has(value)) throw new Error(`Unknown type shorthand: "${value}"`);
+    return { schema: { type: value }, required: false };
+  }
+  if (Array.isArray(value)) {
+    if (value.length !== 1) throw new Error('Array shorthand must have exactly one element describing the item type');
+    const inner = value[0] as FieldDef;
+    if (typeof inner === 'string') return { schema: { type: 'array', items: { type: inner } }, required: false };
+    return { schema: { type: 'array', items: convertObject(inner as Record<string, unknown>) }, required: false };
+  }
+  if (typeof value === 'object' && value !== null) {
+    const v = value as Record<string, unknown>;
+    if (v['type'] && PRIMITIVES.has(v['type'] as string)) {
+      const { required: isReq, ...rest } = v;
+      return { schema: rest, required: !!isReq };
+    }
+    if (v['type'] === 'array' || v['type'] === 'object') {
+      const { required: isReq, ...rest } = v;
+      return { schema: rest, required: !!isReq };
+    }
+    return { schema: convertObject(v), required: false };
+  }
+  throw new Error(`Cannot convert field value: ${JSON.stringify(value)}`);
+}
+
+function convertObject(fields: Record<string, unknown>): Record<string, unknown> {
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+  for (const [key, value] of Object.entries(fields)) {
+    if (key === 'required') continue;
+    const { schema, required: isReq } = convertField(value as FieldDef);
+    properties[key] = schema;
+    if (isReq) required.push(key);
+  }
+  const result: Record<string, unknown> = { type: 'object', properties };
+  if (required.length > 0) result['required'] = required;
+  return result;
+}
+
+export interface ToolDefinition {
+  schema: { type: 'function'; function: Record<string, unknown> };
+  handler: (args: Record<string, unknown>, context: Record<string, unknown>) => Promise<unknown>;
+  echoUserSummaryOnSuccess?: boolean;
+  /**
+   * When true, the runtime will skip a second invocation of this tool in
+   * the same assistant message. Use for "create an agreement"-style tools
+   * where the model is prone to fire two near-identical create calls.
+   */
+  isAgreementCreation?: boolean;
+  /**
+   * When true, the runtime will execute this tool even when no state
+   * action is bound to it. Use for discovery tools (e.g. agent search,
+   * task board) that should always be callable.
+   */
+  isGenericFallback?: boolean;
+}
+
+export interface DefineToolOptions {
+  description?: string;
+  echoUserSummaryOnSuccess?: boolean;
+  isAgreementCreation?: boolean;
+  isGenericFallback?: boolean;
+}
+
+export function defineTool(
+  name: string,
+  params: Record<string, unknown>,
+  handler: (args: Record<string, unknown>, context: Record<string, unknown>) => Promise<unknown>,
+  options: DefineToolOptions = {},
+): ToolDefinition {
+  if (!name || typeof name !== 'string') throw new Error('defineTool: name is required');
+  if (!handler || typeof handler !== 'function') throw new Error('defineTool: handler function is required');
+
+  const parameters = convertObject(params || {});
+  const fn: Record<string, unknown> = { name, parameters };
+  if (options.description) fn['description'] = options.description;
+
+  return {
+    schema: { type: 'function', function: fn },
+    handler,
+    ...(options.echoUserSummaryOnSuccess ? { echoUserSummaryOnSuccess: true } : {}),
+    ...(options.isAgreementCreation ? { isAgreementCreation: true } : {}),
+    ...(options.isGenericFallback ? { isGenericFallback: true } : {}),
+  };
+}

package/src/tools/index.ts

@@ -0,0 +1,5 @@
+export { ToolManager } from './ToolManager.js';
+export { ToolProvider } from './ToolProvider.js';
+export { defineTool } from './defineTool.js';
+// Pure protocol-tool name registry (no handlers, no services).
+export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from '../tasks/protocolRegistry.js';