@botbotgo/kit 1.0.104

package/dist/core/types/Events.d.ts

@@ -0,0 +1,99 @@
+import type { Evidence, ToolError } from "./ToolResult.js";
+/**
+ * Event types emitted by PTCRuntime and observability layer.
+ */
+export type ToolEventType = "TOOL_CALLED" | "TOOL_RESULT" | "POLICY_DENIED" | "HITL_APPROVAL_REQUESTED" | "HITL_APPROVAL_GRANTED" | "HITL_APPROVAL_DENIED" | "RETRY" | "TIMEOUT" | "BUDGET_EXCEEDED" | "JOB_SUBMITTED" | "JOB_COMPLETED" | "JOB_FAILED";
+/**
+ * Base event structure for all tool events.
+ */
+export interface ToolEvent {
+    type: ToolEventType;
+    timestamp: string;
+    requestId: string;
+    taskId: string;
+    toolName: string;
+    traceId?: string;
+    userId?: string;
+}
+/**
+ * Emitted when a tool is called.
+ */
+export interface ToolCalledEvent extends ToolEvent {
+    type: "TOOL_CALLED";
+    argsSummary: string;
+    purpose: string;
+    idempotencyKey?: string;
+}
+/**
+ * Emitted when a tool returns a result.
+ */
+export interface ToolResultEvent extends ToolEvent {
+    type: "TOOL_RESULT";
+    ok: boolean;
+    durationMs: number;
+    resultSummary: string;
+    evidence: Evidence[];
+    error?: ToolError;
+}
+/**
+ * Emitted when policy denies a tool invocation.
+ */
+export interface PolicyDeniedEvent extends ToolEvent {
+    type: "POLICY_DENIED";
+    reason: string;
+    missingCapabilities?: string[];
+}
+/**
+ * Emitted on retry.
+ */
+export interface RetryEvent extends ToolEvent {
+    type: "RETRY";
+    attempt: number;
+    maxRetries: number;
+    reason: string;
+}
+/**
+ * Emitted when human approval is requested (before execute for external_write/destructive).
+ */
+export interface HitlApprovalRequestedEvent extends ToolEvent {
+    type: "HITL_APPROVAL_REQUESTED";
+    sideEffect: string;
+    argsSummary?: string;
+}
+/**
+ * Emitted when human approves the tool invocation.
+ */
+export interface HitlApprovalGrantedEvent extends ToolEvent {
+    type: "HITL_APPROVAL_GRANTED";
+    sideEffect: string;
+}
+/**
+ * Emitted when human denies the tool invocation.
+ */
+export interface HitlApprovalDeniedEvent extends ToolEvent {
+    type: "HITL_APPROVAL_DENIED";
+    sideEffect: string;
+    reason?: string;
+}
+/**
+ * Async job events.
+ */
+export interface JobSubmittedEvent extends ToolEvent {
+    type: "JOB_SUBMITTED";
+    jobId: string;
+}
+export interface JobCompletedEvent extends ToolEvent {
+    type: "JOB_COMPLETED";
+    jobId: string;
+    durationMs: number;
+}
+export interface JobFailedEvent extends ToolEvent {
+    type: "JOB_FAILED";
+    jobId: string;
+    error: string;
+}
+/**
+ * Union type of all tool events.
+ */
+export type AnyToolEvent = ToolCalledEvent | ToolResultEvent | PolicyDeniedEvent | HitlApprovalRequestedEvent | HitlApprovalGrantedEvent | HitlApprovalDeniedEvent | RetryEvent | JobSubmittedEvent | JobCompletedEvent | JobFailedEvent;
+//# sourceMappingURL=Events.d.ts.map

package/dist/core/types/Events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Events.d.ts","sourceRoot":"","sources":["../../../src/core/types/Events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE3D;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,aAAa,GACb,aAAa,GACb,eAAe,GACf,yBAAyB,GACzB,uBAAuB,GACvB,sBAAsB,GACtB,OAAO,GACP,SAAS,GACT,iBAAiB,GACjB,eAAe,GACf,eAAe,GACf,YAAY,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,aAAa,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,SAAS;IAChD,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,SAAS;IAChD,IAAI,EAAE,aAAa,CAAC;IACpB,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,QAAQ,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IAClD,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA2B,SAAQ,SAAS;IAC3D,IAAI,EAAE,yBAAyB,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAyB,SAAQ,SAAS;IACzD,IAAI,EAAE,uBAAuB,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,SAAS;IACxD,IAAI,EAAE,sBAAsB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IAClD,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IAClD,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,eAAe,GACf,eAAe,GACf,iBAAiB,GACjB,0BAA0B,GAC1B,wBAAwB,GACxB,uBAAuB,GACvB,UAAU,GACV,iBAAiB,GACjB,iBAAiB,GACjB,cAAc,CAAC"}

package/dist/core/types/ToolIntent.d.ts

@@ -0,0 +1,40 @@
+import type { Capability } from "./ToolSpec.js";
+/**
+ * Budget constraints for a tool invocation.
+ */
+export interface BudgetConfig {
+    timeoutMs?: number;
+    maxRetries?: number;
+    maxToolCalls?: number;
+}
+/**
+ * Execution context passed from agent-orchestra.
+ * Contains permissions, budget, and observability context.
+ */
+export interface ExecContext {
+    requestId: string;
+    taskId: string;
+    /** Allowed capabilities for this invocation */
+    permissions: Capability[];
+    budget?: BudgetConfig;
+    /** OpenTelemetry-compatible trace ID */
+    traceId?: string;
+    userId?: string;
+    /** Optional: enable dry-run mode for two-phase commit */
+    dryRun?: boolean;
+}
+/**
+ * Tool invocation intent from agent-orchestra.
+ * Represents what the agent wants to do (untrusted input).
+ */
+export interface ToolIntent {
+    /** ToolSpec.name reference */
+    tool: string;
+    /** Untrusted input arguments */
+    args: unknown;
+    /** Human-readable purpose for audit trail */
+    purpose: string;
+    /** Idempotency key: recommended format requestId:taskId:tool */
+    idempotencyKey?: string;
+}
+//# sourceMappingURL=ToolIntent.d.ts.map

package/dist/core/types/ToolIntent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolIntent.d.ts","sourceRoot":"","sources":["../../../src/core/types/ToolIntent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IAEf,+CAA+C;IAC/C,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,IAAI,EAAE,OAAO,CAAC;IACd,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB"}

package/dist/core/types/ToolResult.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Evidence attached to a tool result for audit trail.
+ */
+export interface Evidence {
+    type: "tool" | "file" | "url" | "text" | "metric";
+    ref: string;
+    summary: string;
+    createdAt: string;
+}
+/**
+ * Known error kinds returned by PTC / tools so callers get structured feedback.
+ * Extensions may use createTaggedError(kind, message, details); pipeline maps to ToolError.
+ */
+export type ToolErrorKind = "TOOL_NOT_FOUND" | "INPUT_SCHEMA_INVALID" | "POLICY_DENIED" | "BUDGET_EXCEEDED" | "TIMEOUT" | "UPSTREAM_ERROR" | "OUTPUT_SCHEMA_INVALID" | "PATH_OUTSIDE_SANDBOX" | "FILE_TOO_LARGE" | "HTTP_DISALLOWED_HOST" | "HTTP_TIMEOUT" | "HTTP_TOO_LARGE" | "HITL_DENIED" | "EXEC_INVALID" | "EXEC_SPAWN_ERROR" | "DUCKDUCKGO_INVALID";
+/**
+ * Error information in a tool result.
+ */
+export interface ToolError {
+    kind?: ToolErrorKind;
+    message: string;
+    details?: unknown;
+}
+export type ToolFeedbackStatus = "resolved" | "needs_retry" | "needs_input" | "blocked";
+export interface ToolFeedback {
+    status: ToolFeedbackStatus;
+    message: string;
+    hint?: string;
+    suggested_intent_patch?: Record<string, unknown>;
+    suggested_tool_args?: Record<string, unknown>;
+}
+/**
+ * Unified tool result returned to agent-orchestra.
+ * Always structured, never throws raw exceptions.
+ */
+export interface ToolResult {
+    ok: boolean;
+    result?: unknown;
+    feedback?: ToolFeedback;
+    evidence: Evidence[];
+    error?: ToolError;
+    /** Raw response for debugging (can be disabled in production) */
+    raw?: unknown;
+}
+//# sourceMappingURL=ToolResult.d.ts.map

package/dist/core/types/ToolResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolResult.d.ts","sourceRoot":"","sources":["../../../src/core/types/ToolResult.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GACrB,gBAAgB,GAChB,sBAAsB,GACtB,eAAe,GACf,iBAAiB,GACjB,SAAS,GACT,gBAAgB,GAChB,uBAAuB,GACvB,sBAAsB,GACtB,gBAAgB,GAChB,sBAAsB,GACtB,cAAc,GACd,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,kBAAkB,GAClB,oBAAoB,CAAC;AAEzB;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,aAAa,GAAG,aAAa,GAAG,SAAS,CAAC;AAExF,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sBAAsB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjD,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/C;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,QAAQ,EAAE,QAAQ,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,iEAAiE;IACjE,GAAG,CAAC,EAAE,OAAO,CAAC;CACf"}

package/dist/core/types/ToolSpec.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Unified tool kinds supported by the tools package.
+ */
+export type ToolKind = "mcp" | "langchain" | "n8n" | "comfyui" | "skill" | "function" | "core" | "example";
+/**
+ * Capability declarations for tools.
+ * Used by PolicyEngine for permission gating.
+ */
+export type Capability = "read:web" | "read:fs" | "write:fs" | "read:db" | "write:db" | "network" | "gpu" | "workflow" | "danger:destructive" | "exec";
+/**
+ * HITL (Human-in-the-Loop) side-effect classification.
+ * Used to gate execution: external_write / destructive require human approval when onApprovalRequired is set.
+ */
+export type HitlSideEffect = "none" | "local_write" | "external_write" | "destructive";
+/**
+ * Cost hints for tools, used by Budget and routing.
+ */
+export interface CostHints {
+    latencyMsP50?: number;
+    latencyMsP95?: number;
+    isAsync?: boolean;
+}
+/**
+ * Unified tool specification.
+ * All tool types (MCP, LangChain, n8n, SKILL) are described by this interface.
+ *
+ * Safety: each tool declares capabilities (permission gating) and _meta.hitl.sideEffect
+ * (HITL approval for external_write/destructive). Caller uses these to decide handling.
+ */
+export interface ToolSpec {
+    /** Globally unique name, recommended format: namespace/name */
+    name: string;
+    /** Semver version */
+    version: string;
+    /** Tool kind determines which adapter handles execution */
+    kind: ToolKind;
+    description?: string;
+    tags?: string[];
+    /** JSON Schema for input validation */
+    inputSchema: object;
+    /** JSON Schema for output validation */
+    outputSchema: object;
+    /** Required capabilities for this tool (safety: PolicyEngine gates by ExecContext.permissions) */
+    capabilities: Capability[];
+    costHints?: CostHints;
+    /** HITL and adapter-specific metadata. Adapters may use _meta.sourcePath, _meta.exportName, _meta.projectPath (function), etc. */
+    _meta?: {
+        hitl?: {
+            sideEffect?: HitlSideEffect;
+        };
+        /** Function kind: path to source file relative to projectPath */
+        sourcePath?: string;
+        /** Function kind: export name of the handler */
+        exportName?: string;
+        /** Function/skill kind: project root for resolving sourcePath */
+        projectPath?: string;
+        /** Extension kind: package root for resolving sourcePath */
+        packageRoot?: string;
+    };
+    /** Adapter-specific: endpoint URL (MCP/n8n) */
+    endpoint?: string;
+    /** Adapter-specific: resource identifier (workflowId, promptId, etc.) */
+    resourceId?: string;
+    /** Adapter-specific: implementation reference (LangChain Tool instance, skill handler) */
+    impl?: unknown;
+}
+/**
+ * Normalize tool name: only [a-zA-Z0-9] and "." allowed; all other characters become ".".
+ * Consecutive dots are collapsed to one. Used for registry lookup and storage.
+ */
+export declare function normalizeToolName(name: string): string;
+/** Default permissive input schema when not provided (framework supports auto-derived schema). */
+export declare const DEFAULT_INPUT_SCHEMA: object;
+/** Default permissive output schema when not provided (framework supports auto-derived schema). */
+export declare const DEFAULT_OUTPUT_SCHEMA: object;
+/**
+ * Minimal options to build a ToolSpec. Use with @effect in JSDoc for HITL sideEffect.
+ * Framework fills _meta.hitl.sideEffect from the sideEffect parameter (matches @effect annotation).
+ * inputSchema/outputSchema are optional: when omitted, permissive defaults are used (framework supports auto-derived schema at build time in scan/mcp-build).
+ */
+export interface CreateToolSpecOptions {
+    name: string;
+    version?: string;
+    kind: ToolKind;
+    description?: string;
+    tags?: string[];
+    /** Optional: when omitted, DEFAULT_INPUT_SCHEMA is used. Codegen can derive from handler params. */
+    inputSchema?: object;
+    /** Optional: when omitted, DEFAULT_OUTPUT_SCHEMA is used. Codegen can derive from handler return type. */
+    outputSchema?: object;
+    capabilities: Capability[];
+    costHints?: CostHints;
+    /** HITL: from @effect annotation (none | local_write | external_write | destructive). Default "none". */
+    sideEffect?: HitlSideEffect;
+}
+/**
+ * Build a ToolSpec from minimal options. Use @effect in handler JSDoc as annotation; pass same value as sideEffect.
+ * When inputSchema/outputSchema are omitted, permissive defaults are used (schema can be auto-derived at build time).
+ */
+export declare function createToolSpec(opts: CreateToolSpecOptions): ToolSpec;
+/**
+ * Unified adapter interface.
+ * PTCRuntime looks up adapter by spec.kind and calls adapter.invoke(spec, args, ctx).
+ * spec.name is always the single canonical name (the long name); there is no short name.
+ */
+export interface ToolAdapter {
+    kind: ToolKind;
+    /** Optional: supports dynamic tool discovery */
+    listTools?(): Promise<ToolSpec[]>;
+    /** Execute the tool with validated args. spec.name is the canonical (long) name. */
+    invoke(spec: ToolSpec, args: unknown, ctx: import("./ToolIntent.js").ExecContext): Promise<{
+        result: unknown;
+        raw?: unknown;
+    }>;
+}
+//# sourceMappingURL=ToolSpec.d.ts.map

package/dist/core/types/ToolSpec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolSpec.d.ts","sourceRoot":"","sources":["../../../src/core/types/ToolSpec.ts"],"names":[],"mappings":"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"}

package/dist/core/types/ToolTypeHandler.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Generic tool type handler: scan (discover), load (register), invoke (execute).
+ * Each tool kind has its own invoke path; PTCRuntime dispatches by spec.kind to the
+ * registered ToolAdapter for that kind.
+ *
+ * Invoke by kind:
+ * - core:   handler map → runWithBuiltinContext(handler(args)) — CoreAdapter (builtin-tools)
+ * - example: handler map → runWithExampleContext(handler(args)) — ExampleAdapter (example-tools)
+ * - mcp:    client.callTool({ name, arguments }) — MCPClientAdapter (src/tools/mcp)
+ * - function: dynamic import(spec._meta.sourcePath).then(m => m[exportName](args)) — in-repo adapter TBD; MCP build uses getHandler(name)(args)
+ * - skill:  load skill handler from sourcePath, then run — in-repo adapter TBD; MCP build uses skill-invoker
+ * - n8n:    HTTP to webhook or n8n API — in-repo adapter TBD; MCP build uses n8n-invoker
+ * - langchain: spec.impl.invoke(args) (LangChain Tool) — in-repo adapter TBD
+ *
+ * - scan: discover tools from a path. Optional if the kind does not support path-based discovery (e.g. MCP).
+ * - load: register tools into a registry and/or prepare for invoke. Optional if invoke is via external client.
+ * - invoke: execute the tool (same contract as ToolAdapter.invoke). Required.
+ */
+import type { ToolKind, ToolSpec } from "./ToolSpec.js";
+import type { ToolAdapter } from "./ToolSpec.js";
+import type { ExecContext } from "./ToolIntent.js";
+/** Minimal registry interface for load(); avoids circular dependency on ToolRegistry. */
+export interface ToolRegistryLike {
+    register(spec: ToolSpec): void;
+    bulkRegister(specs: ToolSpec[]): void;
+}
+/** Options for scanning a path for tools of a given kind. */
+export interface ToolTypeScanOptions {
+    /** Project or package root path. */
+    projectPath?: string;
+    /** Glob patterns for files (e.g. ["**\/*.ts"]). Used by function kind. */
+    include?: string[];
+    /** Path to tsconfig.json. Used by function kind. */
+    tsconfigPath?: string;
+    /** Kind-specific options (e.g. includeN8n for scan). */
+    [key: string]: unknown;
+}
+/** Result of scanning: unified ToolSpec[] and any errors/warnings. */
+export interface ToolTypeScanResult {
+    specs: ToolSpec[];
+    errors: Array<{
+        file: string;
+        message: string;
+    }>;
+    warnings?: Array<{
+        file: string;
+        message: string;
+    }>;
+}
+/** Options for loading (registering) tools of a given kind. */
+export interface ToolTypeLoadOptions {
+    /** Namespace for registered tool names (e.g. "pkg"). */
+    namespace?: string;
+    /** Kind-specific options. */
+    [key: string]: unknown;
+}
+/** Result of loading: how many registered and any errors. */
+export interface ToolTypeLoadResult {
+    registered: number;
+    errors: Array<{
+        file: string;
+        message: string;
+    }>;
+}
+/**
+ * Generic tool type handler: scan, load, invoke.
+ * Extends ToolAdapter so a handler can be registered with PTCRuntime as the adapter for its kind.
+ */
+export interface ToolTypeHandler extends ToolAdapter {
+    readonly kind: ToolKind;
+    /**
+     * Discover tools from a path. Optional if this kind does not support path-based discovery.
+     */
+    scan?(path: string, options?: ToolTypeScanOptions): Promise<ToolTypeScanResult> | ToolTypeScanResult;
+    /**
+     * Register tools into registry and/or prepare for invoke. Optional if this kind
+     * only supports invoke via an external client (e.g. MCP client already connected).
+     */
+    load?(path: string, registry: ToolRegistryLike, options?: ToolTypeLoadOptions): Promise<ToolTypeLoadResult> | ToolTypeLoadResult;
+    /**
+     * Execute the tool. Same contract as ToolAdapter.invoke.
+     */
+    invoke(spec: ToolSpec, args: unknown, ctx: ExecContext): Promise<{
+        result: unknown;
+        raw?: unknown;
+    }>;
+}
+//# sourceMappingURL=ToolTypeHandler.d.ts.map

package/dist/core/types/ToolTypeHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolTypeHandler.d.ts","sourceRoot":"","sources":["../../../src/core/types/ToolTypeHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,yFAAyF;AACzF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/B,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;CACvC;AAED,6DAA6D;AAC7D,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,6DAA6D;AAC7D,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClD;AAED;;;GAGG;AACH,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAExB;;OAEG;IACH,IAAI,CAAC,CACH,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAAC;IAEpD;;;OAGG;IACH,IAAI,CAAC,CACH,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAAC;IAEpD;;OAEG;IACH,MAAM,CACJ,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,WAAW,GACf,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAChD"}

package/dist/core/types/index.d.ts

@@ -0,0 +1,7 @@
+export type { ToolKind, Capability, CostHints, ToolSpec, ToolAdapter, HitlSideEffect, CreateToolSpecOptions, } from "./ToolSpec.js";
+export { createToolSpec, DEFAULT_INPUT_SCHEMA, DEFAULT_OUTPUT_SCHEMA, } from "./ToolSpec.js";
+export type { BudgetConfig, ExecContext, ToolIntent, } from "./ToolIntent.js";
+export type { Evidence, ToolError, ToolErrorKind, ToolResult, } from "./ToolResult.js";
+export type { ToolEventType, ToolEvent, ToolCalledEvent, ToolResultEvent, PolicyDeniedEvent, RetryEvent, JobSubmittedEvent, JobCompletedEvent, JobFailedEvent, AnyToolEvent, } from "./Events.js";
+export type { ToolTypeScanOptions, ToolTypeScanResult, ToolTypeLoadOptions, ToolTypeLoadResult, ToolRegistryLike, ToolTypeHandler, } from "./ToolTypeHandler.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,QAAQ,EACR,UAAU,EACV,SAAS,EACT,QAAQ,EACR,WAAW,EACX,cAAc,EACd,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,YAAY,EACZ,WAAW,EACX,UAAU,GACX,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,QAAQ,EACR,SAAS,EACT,aAAa,EACb,UAAU,GACX,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,aAAa,EACb,SAAS,EACT,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,GAChB,MAAM,sBAAsB,CAAC"}