vellum 0.0.16 → 0.2.0

package/src/tools/terminal/shell.ts

@@ -0,0 +1,257 @@
+import { spawn, execSync } from 'node:child_process';
+import { platform } from 'node:os';
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { registerTool } from '../registry.js';
+import { getConfig } from '../../config/loader.js';
+import { getLogger } from '../../util/logger.js';
+import { redactSecrets } from '../../security/secret-scanner.js';
+import { wrapCommand } from './sandbox.js';
+import { formatShellOutput } from '../shared/shell-output.js';
+import { buildSanitizedEnv } from './safe-env.js';
+import {
+  getOrStartSession,
+  getSessionEnv,
+} from '../network/script-proxy/index.js';
+import { getDataDir } from '../../util/platform.js';
+import { resolveCredentialRef } from '../credentials/resolve.js';
+import { buildCredentialRefTrace } from '../network/script-proxy/logging.js';
+
+const log = getLogger('shell-tool');
+
+/**
+ * Returns the host address to bind the proxy to when Docker sandbox is active.
+ * On macOS, Docker Desktop routes host.docker.internal through the VM to
+ * 127.0.0.1, so no bind change is needed. On Linux, we need to bind to the
+ * Docker bridge gateway IP so containers can reach the proxy.
+ */
+function getDockerProxyHost(): string {
+  if (platform() !== 'linux') return '127.0.0.1';
+
+  try {
+    // Docker bridge gateway is the default route from inside docker0 network.
+    // `ip -4 addr show docker0` outputs the gateway IP assigned to the bridge.
+    const output = execSync('ip -4 addr show docker0 2>/dev/null', { encoding: 'utf-8' });
+    const match = output.match(/inet\s+(\d+\.\d+\.\d+\.\d+)/);
+    if (match) return match[1];
+  } catch {
+    // docker0 interface may not exist (e.g. rootless Docker, custom networks)
+  }
+  // Fallback: bind to localhost when docker0 is unavailable (e.g. rootless
+  // Docker, custom networks). This avoids EADDRNOTAVAIL from 172.17.0.1 while
+  // keeping the proxy off public interfaces — 0.0.0.0 would expose the
+  // unauthenticated credential proxy to the network. Docker containers won't
+  // be able to reach localhost on the host, but that's a safer failure mode.
+  return '127.0.0.1';
+}
+
+class ShellTool implements Tool {
+  name = 'bash';
+  description = 'Execute a shell command on the local machine';
+  category = 'terminal';
+  defaultRiskLevel = RiskLevel.Medium;
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          command: {
+            type: 'string',
+            description: 'The shell command to execute',
+          },
+          reason: {
+            type: 'string',
+            description: 'Brief human-readable explanation of what this command does and why, shown to the user in the permission prompt (e.g. "to find available location services")',
+          },
+          timeout_seconds: {
+            type: 'number',
+            description: 'Optional timeout in seconds. Defaults to the configured default (120s). Cannot exceed the configured maximum.',
+          },
+          network_mode: {
+            type: 'string',
+            enum: ['off', 'proxied'],
+            description: 'Network access mode for the command. "off" (default) blocks network access; "proxied" routes traffic through the credential proxy.',
+          },
+          credential_ids: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Optional list of credential IDs to inject via the proxy when network_mode is "proxied".',
+          },
+        },
+        required: ['command', 'reason'],
+      },
+    };
+  }
+
+  async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+    const command = input.command as string;
+    if (!command || typeof command !== 'string') {
+      return { content: 'Error: command is required and must be a string', isError: true };
+    }
+
+    // Reject commands containing null bytes — they cause truncation at the
+    // OS level while the parser sees the full string, enabling bypass.
+    if (command.includes('\0')) {
+      return { content: 'Error: command contains null bytes', isError: true };
+    }
+
+    const networkMode: 'off' | 'proxied' =
+      input.network_mode === 'proxied' ? 'proxied' : 'off';
+
+    const rawCredentialRefs: string[] = [];
+    if (Array.isArray(input.credential_ids)) {
+      for (const id of input.credential_ids) {
+        if (typeof id === 'string' && id.length > 0) {
+          rawCredentialRefs.push(id);
+        }
+      }
+    }
+
+    // Resolve credential refs (UUID or service/field) to canonical UUIDs.
+    // Fail fast if any ref is unresolvable — partial execution with missing
+    // credentials is worse than a clear error.
+    const credentialIds: string[] = [];
+    if (networkMode === 'proxied' && rawCredentialRefs.length > 0) {
+      const unresolvedRefs: string[] = [];
+      const seenIds = new Set<string>();
+      for (const ref of rawCredentialRefs) {
+        const resolved = resolveCredentialRef(ref);
+        if (!resolved) {
+          unresolvedRefs.push(ref);
+        } else if (!seenIds.has(resolved.credentialId)) {
+          seenIds.add(resolved.credentialId);
+          credentialIds.push(resolved.credentialId);
+        }
+      }
+      if (unresolvedRefs.length > 0) {
+        log.warn({ trace: buildCredentialRefTrace(rawCredentialRefs, credentialIds, unresolvedRefs) }, 'Credential ref resolution failed');
+        return {
+          content: `Error: unknown credential reference(s): ${unresolvedRefs.join(', ')}. Use credential_store list to see available credentials.`,
+          isError: true,
+        };
+      }
+      log.debug({ trace: buildCredentialRefTrace(rawCredentialRefs, credentialIds, []) }, 'Credential refs resolved');
+    } else {
+      credentialIds.push(...rawCredentialRefs);
+    }
+
+    const config = getConfig();
+    const { shellDefaultTimeoutSec, shellMaxTimeoutSec } = config.timeouts;
+    const requestedSec = typeof input.timeout_seconds === 'number' ? input.timeout_seconds : shellDefaultTimeoutSec;
+    const timeoutSec = Math.max(1, Math.min(requestedSec, shellMaxTimeoutSec));
+    const timeoutMs = timeoutSec * 1000;
+
+    log.info({ command: redactSecrets(command), cwd: context.workingDir, timeoutSec, networkMode, rawRefs: rawCredentialRefs, credentialIds }, 'Executing shell command');
+
+    // Resolve sandbox config early — needed both for proxy env and command wrapping.
+    const sandboxConfig = context.sandboxOverride != null
+      ? { ...config.sandbox, enabled: context.sandboxOverride }
+      : config.sandbox;
+    const isDockerSandbox = sandboxConfig.enabled && sandboxConfig.backend === 'docker';
+
+    // Acquire proxy session if proxied mode is requested.
+    // `getOrStartSession` serializes per-conversation so concurrent proxied
+    // commands share a single session instead of each creating one.
+    // Sessions are NOT stopped here — the session manager's idle timer handles
+    // cleanup after all commands finish (see resetIdleTimer / stopAllSessions).
+    let proxyEnv: import('../network/script-proxy/types.js').ProxyEnvVars | null = null;
+
+    if (networkMode === 'proxied') {
+      try {
+        const { session } = await getOrStartSession(
+          context.conversationId,
+          credentialIds,
+          undefined,
+          getDataDir(),
+          context.proxyApprovalCallback,
+          isDockerSandbox ? { listenHost: getDockerProxyHost() } : undefined,
+        );
+        proxyEnv = getSessionEnv(session.id, { dockerMode: isDockerSandbox });
+      } catch (err) {
+        log.error({ err }, 'Failed to start proxy session');
+        return {
+          content: `Error: failed to start proxy session — ${err instanceof Error ? err.message : String(err)}`,
+          isError: true,
+        };
+      }
+    }
+
+    const env = buildSanitizedEnv();
+    if (proxyEnv) {
+      Object.assign(env, proxyEnv);
+    }
+
+    const result = await new Promise<ToolExecutionResult>((resolve) => {
+      const stdoutChunks: Buffer[] = [];
+      const stderrChunks: Buffer[] = [];
+      let timedOut = false;
+
+      const wrapped = wrapCommand(command, context.workingDir, sandboxConfig, { networkMode });
+      const child = spawn(wrapped.command, wrapped.args, {
+        cwd: context.workingDir,
+        env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      const timer = setTimeout(() => {
+        timedOut = true;
+        child.kill('SIGKILL');
+      }, timeoutMs);
+
+      // Cooperative cancellation via AbortSignal
+      const onAbort = () => {
+        child.kill('SIGKILL');
+      };
+      if (context.signal) {
+        if (context.signal.aborted) {
+          child.kill('SIGKILL');
+        } else {
+          context.signal.addEventListener('abort', onAbort, { once: true });
+        }
+      }
+
+      child.stdout.on('data', (data: Buffer) => {
+        stdoutChunks.push(data);
+        context.onOutput?.(data.toString());
+      });
+
+      child.stderr.on('data', (data: Buffer) => {
+        stderrChunks.push(data);
+        context.onOutput?.(data.toString());
+      });
+
+      child.on('close', (code) => {
+        clearTimeout(timer);
+        context.signal?.removeEventListener('abort', onAbort);
+
+        const stdout = Buffer.concat(stdoutChunks).toString();
+        const stderr = Buffer.concat(stderrChunks).toString();
+        const fmtResult = formatShellOutput(stdout, stderr, code, timedOut, timeoutSec);
+
+        resolve({
+          content: fmtResult.content,
+          isError: fmtResult.isError,
+          status: fmtResult.status,
+        });
+      });
+
+      child.on('error', (err) => {
+        clearTimeout(timer);
+        context.signal?.removeEventListener('abort', onAbort);
+        resolve({
+          content: `Error spawning command: ${err.message}${(err as NodeJS.ErrnoException).code === 'ENOENT' ? '. The command was not found — check that it is installed and in PATH.' : ''}`,
+          isError: true,
+        });
+      });
+    });
+
+    return result;
+  }
+}
+
+export const shellTool: Tool = new ShellTool();
+registerTool(shellTool);

package/src/tools/tool-manifest.ts

@@ -0,0 +1,250 @@
+/**
+ * Declarative tool manifest — single place to inspect what gets registered.
+ *
+ * Each entry describes HOW a tool (or group of tools) gets loaded and
+ * registered.  `initializeTools()` in `registry.ts` iterates this list
+ * so adding/removing tools only requires editing this manifest.
+ */
+
+import { RiskLevel } from '../permissions/types.js';
+import type { LazyToolDescriptor } from './registry.js';
+import type { Tool } from './types.js';
+import { memorySearchTool, memorySaveTool, memoryUpdateTool } from './memory/register.js';
+import { credentialStoreTool } from './credentials/vault.js';
+import { accountManageTool } from './credentials/account-registry.js';
+import { reminderTool } from './reminder/reminder.js';
+import { screenWatchTool } from './watch/screen-watch.js';
+import { vellumSkillsCatalogTool } from './skills/vellum-catalog.js';
+import { documentCreateTool, documentUpdateTool } from './document/index.js';
+import { cliDiscoverTool } from './host-terminal/cli-discover.js';
+import { followupCreateTool, followupListTool, followupResolveTool } from './followups/index.js';
+import { taskSaveTool, taskRunTool, taskListTool, taskDeleteTool, taskListShowTool, taskListAddTool } from './tasks/index.js';
+import {
+  subagentSpawnTool,
+  subagentStatusTool,
+  subagentAbortTool,
+  subagentMessageTool,
+  subagentReadTool,
+} from './subagent/index.js';
+
+// ── Eager side-effect modules ───────────────────────────────────────
+// Importing these modules triggers a top-level `registerTool()` call.
+
+export const eagerModules: string[] = [
+  './filesystem/read.js',
+  './filesystem/write.js',
+  './filesystem/edit.js',
+  './network/web-search.js',
+  './network/web-fetch.js',
+  './skills/load.js',
+  './skills/scaffold-managed.js',
+  './skills/delete-managed.js',
+  './system/request-permission.js',
+  './schedule/create.js',
+  './schedule/list.js',
+  './schedule/update.js',
+  './schedule/delete.js',
+  './watcher/create.js',
+  './watcher/list.js',
+  './watcher/update.js',
+  './watcher/delete.js',
+  './watcher/digest.js',
+  './playbooks/playbook-create.js',
+  './playbooks/playbook-list.js',
+  './playbooks/playbook-update.js',
+  './playbooks/playbook-delete.js',
+  './contacts/contact-upsert.js',
+  './contacts/contact-search.js',
+  './contacts/contact-merge.js',
+  './assets/search.js',
+  './assets/materialize.js',
+  './filesystem/view-image.js',
+];
+
+// Tool names registered by the eager modules above.  Listed explicitly so
+// initializeTools() can recognise ESM-cached eager-module tools that were
+// already in the registry before init ran (e.g. when a test file imports
+// an eager module at the top level).
+export const eagerModuleToolNames: string[] = [
+  'file_read',
+  'file_write',
+  'file_edit',
+  'web_search',
+  'web_fetch',
+  'skill_load',
+  'scaffold_managed_skill',
+  'delete_managed_skill',
+  'request_system_permission',
+  'schedule_create',
+  'schedule_list',
+  'schedule_update',
+  'schedule_delete',
+  'watcher_create',
+  'watcher_list',
+  'watcher_update',
+  'watcher_delete',
+  'watcher_digest',
+  'playbook_create',
+  'playbook_list',
+  'playbook_update',
+  'playbook_delete',
+  'contact_upsert',
+  'contact_search',
+  'contact_merge',
+  'asset_search',
+  'asset_materialize',
+  'view_image',
+];
+
+// ── Explicit tool instances ─────────────────────────────────────────
+// Tools exported as instances — registered by initializeTools() without
+// relying on import side effects.
+
+export const explicitTools: Tool[] = [
+  memorySearchTool,
+  memorySaveTool,
+  memoryUpdateTool,
+  credentialStoreTool,
+  accountManageTool,
+  reminderTool,
+  screenWatchTool,
+  vellumSkillsCatalogTool,
+  documentCreateTool,
+  documentUpdateTool,
+  cliDiscoverTool,
+  followupCreateTool,
+  followupListTool,
+  followupResolveTool,
+  taskSaveTool,
+  taskRunTool,
+  taskListTool,
+  taskDeleteTool,
+  taskListShowTool,
+  taskListAddTool,
+  subagentSpawnTool,
+  subagentStatusTool,
+  subagentAbortTool,
+  subagentMessageTool,
+  subagentReadTool,
+];
+
+// ── Lazy tool descriptors ───────────────────────────────────────────
+// Tools that defer module loading until first invocation.
+
+export const lazyTools: LazyToolDescriptor[] = [
+  {
+    name: 'evaluate_typescript_code',
+    description: 'Evaluate a TypeScript snippet in an isolated sandbox. Use this to test code before persisting it as a managed skill.',
+    category: 'terminal',
+    defaultRiskLevel: RiskLevel.High,
+    definition: {
+      name: 'evaluate_typescript_code',
+      description: 'Evaluate a TypeScript snippet in an isolated sandbox. Use this to test code before persisting it as a managed skill.',
+      input_schema: {
+        type: 'object',
+        properties: {
+          code: {
+            type: 'string',
+            description: 'The TypeScript source code to evaluate. Must export a `default` or `run` function.',
+          },
+          mock_input_json: {
+            type: 'string',
+            description: 'Optional JSON string to pass as input. Defaults to "{}".',
+          },
+          timeout_seconds: {
+            type: 'number',
+            description: 'Optional timeout in seconds (1-20). Defaults to 10.',
+          },
+          filename: {
+            type: 'string',
+            description: 'Optional filename for the snippet (default: "snippet.ts").',
+          },
+          entrypoint: {
+            type: 'string',
+            enum: ['default', 'run'],
+            description: 'Which export to call: "default" or "run". Defaults to "default".',
+          },
+          max_output_chars: {
+            type: 'number',
+            description: 'Optional max output characters (1-25000). Defaults to 25000.',
+          },
+        },
+        required: ['code'],
+      },
+    },
+    loader: async () => {
+      const mod = await import('./terminal/evaluate-typescript.js');
+      return mod.evaluateTypescriptTool;
+    },
+  },
+  {
+    name: 'bash',
+    description: 'Execute a shell command on the local machine',
+    category: 'terminal',
+    defaultRiskLevel: RiskLevel.Medium,
+    definition: {
+      name: 'bash',
+      description: 'Execute a shell command on the local machine',
+      input_schema: {
+        type: 'object',
+        properties: {
+          command: {
+            type: 'string',
+            description: 'The shell command to execute',
+          },
+          timeout_seconds: {
+            type: 'number',
+            description: 'Optional timeout in seconds. Defaults to the configured default (120s). Cannot exceed the configured maximum.',
+          },
+          network_mode: {
+            type: 'string',
+            enum: ['off', 'proxied'],
+            description: 'Network access mode for the command. "off" (default) blocks network access; "proxied" routes traffic through the credential proxy.',
+          },
+          credential_ids: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Optional list of credential IDs to inject via the proxy when network_mode is "proxied".',
+          },
+        },
+        required: ['command'],
+      },
+    },
+    loader: async () => {
+      const mod = await import('./terminal/shell.js');
+      return mod.shellTool;
+    },
+  },
+  {
+    name: 'swarm_delegate',
+    description: 'Decompose a complex task into parallel specialist subtasks and execute them concurrently.',
+    category: 'orchestration',
+    defaultRiskLevel: RiskLevel.Medium,
+    definition: {
+      name: 'swarm_delegate',
+      description: 'Decompose a complex task into parallel specialist subtasks and execute them concurrently. Use this for multi-part tasks that benefit from parallel research, coding, and review.',
+      input_schema: {
+        type: 'object',
+        properties: {
+          objective: {
+            type: 'string',
+            description: 'The complex task to decompose and execute in parallel',
+          },
+          context: {
+            type: 'string',
+            description: 'Optional additional context about the task or codebase',
+          },
+          max_workers: {
+            type: 'number',
+            description: 'Maximum concurrent workers (1-6, default from config)',
+          },
+        },
+        required: ['objective'],
+      },
+    },
+    loader: async () => {
+      const mod = await import('./swarm/delegate.js');
+      return mod.swarmDelegateTool;
+    },
+  },
+];

package/src/tools/types.ts

@@ -0,0 +1,177 @@
+import type { RiskLevel, AllowlistOption, ScopeOption, ToolPrincipalKind } from '../permissions/types.js';
+import type { ToolDefinition, ContentBlock } from '../providers/types.js';
+import type { SecretPromptResult } from '../permissions/secret-prompter.js';
+
+export type ExecutionTarget = 'sandbox' | 'host';
+
+interface ToolLifecycleEventBase {
+  toolName: string;
+  input: Record<string, unknown>;
+  workingDir: string;
+  sessionId: string;
+  conversationId: string;
+  requestId?: string;
+  executionTarget?: ExecutionTarget;
+  /** Security principal kind (e.g. 'core', 'skill', or 'task'). */
+  principalKind?: ToolPrincipalKind;
+  /** Security principal ID (skill ID when principalKind is 'skill'; task ID when 'task'). */
+  principalId?: string;
+  /** Content-hash of the principal's source at invocation time. */
+  principalVersion?: string;
+}
+
+export interface ToolExecutionStartEvent extends ToolLifecycleEventBase {
+  type: 'start';
+  startedAtMs: number;
+}
+
+export interface ToolPermissionPromptEvent extends ToolLifecycleEventBase {
+  type: 'permission_prompt';
+  riskLevel: string;
+  reason: string;
+  allowlistOptions: AllowlistOption[];
+  scopeOptions: ScopeOption[];
+  diff?: DiffInfo;
+  sandboxed?: boolean;
+  persistentDecisionsAllowed?: boolean;
+}
+
+export interface ToolPermissionDeniedEvent extends ToolLifecycleEventBase {
+  type: 'permission_denied';
+  riskLevel: string;
+  decision: 'deny' | 'always_deny';
+  reason: string;
+  durationMs: number;
+}
+
+export interface ToolExecutedEvent extends ToolLifecycleEventBase {
+  type: 'executed';
+  riskLevel: string;
+  decision: string;
+  durationMs: number;
+  result: ToolExecutionResult;
+}
+
+export interface ToolExecutionErrorEvent extends ToolLifecycleEventBase {
+  type: 'error';
+  riskLevel: string;
+  decision: string;
+  durationMs: number;
+  errorMessage: string;
+  isExpected: boolean;
+  errorName?: string;
+  errorStack?: string;
+}
+
+export interface ToolSecretDetectedEvent extends ToolLifecycleEventBase {
+  type: 'secret_detected';
+  matches: Array<{ type: string; redactedValue: string }>;
+  action: 'redact' | 'warn' | 'block' | 'prompt';
+  detectedAtMs: number;
+}
+
+export type ToolLifecycleEvent =
+  | ToolExecutionStartEvent
+  | ToolPermissionPromptEvent
+  | ToolPermissionDeniedEvent
+  | ToolExecutedEvent
+  | ToolExecutionErrorEvent
+  | ToolSecretDetectedEvent;
+
+export type ToolLifecycleEventHandler = (event: ToolLifecycleEvent) => void | Promise<void>;
+
+export type ProxyToolResolver = (
+  toolName: string,
+  input: Record<string, unknown>,
+) => Promise<ToolExecutionResult>;
+
+export interface ToolContext {
+  workingDir: string;
+  sessionId: string;
+  conversationId: string;
+  /** Per-message request ID for log correlation across session/connection boundaries. */
+  requestId?: string;
+  /** Optional callback for streaming incremental output to the client. */
+  onOutput?: (chunk: string) => void;
+  /** Abort signal for cooperative cancellation. Tools should check this periodically. */
+  signal?: AbortSignal;
+  /** Per-session sandbox override. When set, takes precedence over the global config. */
+  sandboxOverride?: boolean;
+  /** Optional callback for tool lifecycle events (start/prompt/deny/execute/error/secret_detected). */
+  onToolLifecycleEvent?: ToolLifecycleEventHandler;
+  /** Optional resolver for proxy tools — delegates execution to an external client. */
+  proxyToolResolver?: ProxyToolResolver;
+  /** When set, only tools in this set may execute. Tools outside the set are blocked with an error. */
+  allowedToolNames?: Set<string>;
+  /** Principal that owns this tool invocation (set by executor from tool metadata). */
+  principal?: { kind?: string; id?: string; version?: string };
+  /** Request user confirmation for a sub-tool operation (used by claude_code tool). */
+  requestConfirmation?: (req: {
+    toolName: string;
+    input: Record<string, unknown>;
+    riskLevel: string;
+    executionTarget?: ExecutionTarget;
+    /** Principal that owns the parent tool invocation. */
+    principal?: { kind?: string; id?: string; version?: string };
+  }) => Promise<{ decision: 'allow' | 'deny' }>;
+  /** Prompt the user for a secret value via native SecureField UI. */
+  requestSecret?: (params: {
+    service: string;
+    field: string;
+    label: string;
+    description?: string;
+    placeholder?: string;
+    purpose?: string;
+    allowedTools?: string[];
+    allowedDomains?: string[];
+  }) => Promise<SecretPromptResult>;
+  /** Optional callback to send a message to the connected IPC client (e.g. open_url). */
+  sendToClient?: (msg: { type: string; [key: string]: unknown }) => void;
+  /** True when an interactive IPC client is connected (not just a no-op callback). */
+  isInteractive?: boolean;
+  /** Memory scope ID from the session's memory policy, so memory tools can target the correct scope. */
+  memoryScopeId?: string;
+  /** When true, tools with private side-effects should always prompt for confirmation. */
+  forcePromptSideEffects?: boolean;
+  /** Approval callback for proxy policy decisions that require user confirmation. */
+  proxyApprovalCallback?: import('./network/script-proxy/types.js').ProxyApprovalCallback;
+}
+
+export interface DiffInfo {
+  filePath: string;
+  oldContent: string;
+  newContent: string;
+  isNewFile: boolean;
+}
+
+export interface ToolExecutionResult {
+  content: string;
+  isError: boolean;
+  diff?: DiffInfo;
+  /** Optional status message for display (e.g. timeout, truncation). */
+  status?: string;
+  /** Optional rich content blocks (e.g. images) to include alongside text in the tool result. */
+  contentBlocks?: ContentBlock[];
+}
+
+export interface Tool {
+  name: string;
+  description: string;
+  category: string;
+  defaultRiskLevel: RiskLevel;
+  /** When set to 'proxy', the tool is forwarded to a connected client rather than executed locally. */
+  executionMode?: 'local' | 'proxy';
+  /** Whether this tool is a core built-in or provided by a skill. */
+  origin?: 'core' | 'skill';
+  /** If origin is 'skill', the ID of the owning skill. */
+  ownerSkillId?: string;
+  /** Content-hash of the owning skill's source at registration time. */
+  ownerSkillVersionHash?: string;
+  /** Whether the owning skill is bundled with the daemon (trusted first-party). */
+  ownerSkillBundled?: boolean;
+  /** Declared execution target from the skill manifest. Used by resolveExecutionTarget
+   * to accurately label lifecycle events for skill-provided tools. */
+  executionTarget?: ExecutionTarget;
+  getDefinition(): ToolDefinition;
+  execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult>;
+}