copperhead 0.10.0 → 0.11.0

package/src/agent/types.ts

@@ -35,11 +35,16 @@ export interface Turn {
 export interface ChatOpts {
   maxTokens?: number;
   /**
-   * Liveness callback for the loop's heartbeat (5.1). A streaming provider calls
-   * it as output arrives, passing the cumulative streamed-output length in chars,
-   * so a slow turn can be told apart from a hung one. Providers that don't stream
-   * simply never call it (the heartbeat still reports elapsed time). Never used
-   * for billing — real token usage is reported once, on the returned Turn.
+   * Progress callback (5.1). A streaming provider calls it as the turn makes
+   * progress, passing the cumulative streamed-output length in chars. The loop
+   * uses it twice: the heartbeat shows the count, so a slow turn can be told
+   * apart from a hung one, and every call restarts the turn's inactivity
+   * watchdog, so a long turn that keeps producing output is not aborted as hung.
+   * Call it on any progress (thinking, block boundaries), not only new text; an
+   * unchanged count is fine. Providers that don't stream simply never call it
+   * (the heartbeat still reports elapsed time, and the watchdog acts as a
+   * whole-turn deadline). Never used for billing — real token usage is reported
+   * once, on the returned Turn.
    */
   onStream?: (streamedChars: number) => void;
 }

package/src/capabilities/define.ts

@@ -0,0 +1,88 @@
+import type { ToolSchema } from '../agent/types.js';
+import type { RunContext } from '../agent/context.js';
+import type { ToolResult, ViewHint } from '../agent/envelope.js';
+
+export interface CatalogTool {
+  kind: 'tool';
+  name: string;
+  version: number;
+  viewHint: ViewHint;
+  schema: ToolSchema;
+  gate: (ctx: RunContext) => boolean;
+  /** Own gate as declared, before the registry applies the tools-conjunction. */
+  ownGate: (ctx: RunContext) => boolean;
+  handler: (ctx: RunContext, args: Record<string, unknown>) => Promise<ToolResult>;
+}
+
+export interface CatalogSkill {
+  kind: 'skill';
+  name: string;
+  version: number;
+  viewHint: ViewHint;
+  schema: ToolSchema;
+  gate: (ctx: RunContext) => boolean;
+  ownGate: (ctx: RunContext) => boolean;
+  /** False when `gate` was omitted and should default to the tools-conjunction. */
+  gateProvided: boolean;
+  tools: string[];
+  prompt: (ctx: RunContext, args: Record<string, unknown>) => string;
+  isComplete: (ctx: RunContext, args: Record<string, unknown>) => Promise<boolean> | boolean;
+  maxTurns?: number;
+}
+
+export type CatalogEntry = CatalogTool | CatalogSkill;
+
+export interface ToolInit {
+  schema: ToolSchema;
+  version: number;
+  viewHint: ViewHint;
+  gate: (ctx: RunContext) => boolean;
+  handler: (ctx: RunContext, args: Record<string, unknown>) => Promise<ToolResult>;
+}
+
+export interface SkillInit {
+  schema: ToolSchema;
+  version: number;
+  viewHint: ViewHint;
+  tools: string[];
+  prompt: (ctx: RunContext, args: Record<string, unknown>) => string;
+  isComplete: (ctx: RunContext, args: Record<string, unknown>) => Promise<boolean> | boolean;
+  maxTurns?: number;
+  gate?: (ctx: RunContext) => boolean;
+}
+
+/** Identity helper: freeze defaults and tag the tier. */
+export function defineTool(def: ToolInit): CatalogTool {
+  return {
+    kind: 'tool',
+    name: def.schema.name,
+    version: def.version,
+    viewHint: def.viewHint,
+    schema: def.schema,
+    gate: def.gate,
+    ownGate: def.gate,
+    handler: def.handler,
+  };
+}
+
+/**
+ * Identity helper. When `gate` is omitted the skill is available only if every
+ * declared tool's gate is true (applied by the registry at list-time).
+ */
+export function defineSkill(def: SkillInit): CatalogSkill {
+  const ownGate = def.gate ?? ((_ctx: RunContext) => true);
+  return {
+    kind: 'skill',
+    name: def.schema.name,
+    version: def.version,
+    viewHint: def.viewHint,
+    schema: def.schema,
+    gate: ownGate,
+    ownGate,
+    gateProvided: def.gate !== undefined,
+    tools: def.tools,
+    prompt: def.prompt,
+    isComplete: def.isComplete,
+    ...(def.maxTurns !== undefined ? { maxTurns: def.maxTurns } : {}),
+  };
+}