@bradygaster/squad-sdk 0.8.25 → 0.9.0

package/dist/skills/handler-types.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Type system for the skill-script model.
+ *
+ * This module defines the complete type contract for backend skills in `.copilot/skills/`.
+ * Skills contain `scripts/` directories with executable JS handlers that replace built-in
+ * tool handlers in ToolRegistry.
+ *
+ * The skill-script model enables stateful, framework-aware backends for tasks, decisions,
+ * memories, and logging concerns. Handlers are ordinary async functions that return
+ * SquadToolResult values.
+ */
+import type { SquadToolResult, SquadTool } from "../adapter/types.js";
+/**
+ * Arguments for squad_create_issue.
+ * All tool arg interfaces include [key: string]: unknown for skill-documented extensions.
+ */
+export interface CreateIssueArgs {
+    title: string;
+    body?: string;
+    assignee?: string;
+    [key: string]: unknown;
+}
+/**
+ * Arguments for squad_update_issue.
+ */
+export interface UpdateIssueArgs {
+    issueId: string | number;
+    title?: string;
+    body?: string;
+    [key: string]: unknown;
+}
+/**
+ * Arguments for squad_list_issues.
+ */
+export interface ListIssuesArgs {
+    status?: "all" | "open" | "closed";
+    limit?: number;
+    [key: string]: unknown;
+}
+/**
+ * Arguments for squad_close_issue.
+ */
+export interface CloseIssueArgs {
+    issueId: string | number;
+    comment?: string;
+    [key: string]: unknown;
+}
+/**
+ * Arguments for squad_create_decision.
+ */
+export interface CreateDecisionArgs {
+    author: string;
+    summary: string;
+    body: string;
+    [key: string]: unknown;
+}
+/**
+ * Arguments for squad_list_decisions.
+ */
+export interface ListDecisionsArgs {
+    status?: "all" | "pending" | "merged";
+    limit?: number;
+    [key: string]: unknown;
+}
+/**
+ * Arguments for squad_merge_decision.
+ */
+export interface MergeDecisionArgs {
+    slugs?: string[];
+    [key: string]: unknown;
+}
+/**
+ * Arguments for squad_create_memory.
+ */
+export interface CreateMemoryArgs {
+    content: string;
+    agent?: string;
+    [key: string]: unknown;
+}
+/**
+ * Arguments for squad_list_memories.
+ */
+export interface ListMemoriesArgs {
+    agent?: string;
+    limit?: number;
+    [key: string]: unknown;
+}
+/**
+ * Arguments for squad_create_log.
+ */
+export interface CreateLogArgs {
+    kind: "orchestration" | "session";
+    content: string;
+    agent?: string;
+    [key: string]: unknown;
+}
+/**
+ * Arguments for squad_list_logs.
+ */
+export interface ListLogsArgs {
+    kind?: "orchestration" | "session";
+    limit?: number;
+    [key: string]: unknown;
+}
+/**
+ * Skill handler function.
+ *
+ * @param args - Tool input matching the tool's schema
+ * @param config - Non-framework keys from the tracking config entry (excludes 'skill', 'disposeTimeoutMs')
+ * @returns SquadToolResult (string or SquadToolResultObject)
+ */
+export type SkillHandler<TArgs = unknown> = (args: TArgs, config: Record<string, unknown>) => Promise<SquadToolResult> | SquadToolResult;
+/**
+ * Lifecycle hooks for stateful backend skills.
+ * lifecycle.js in the scripts/ dir exports these.
+ */
+export interface HandlerLifecycle {
+    /**
+     * Called once after handler resolution, before first tool call.
+     * init() must be idempotent.
+     */
+    init?(config: Record<string, unknown>): Promise<void>;
+    /**
+     * Called once at session end.
+     * Must be safe to call even if init() partially failed.
+     */
+    dispose?(): Promise<void>;
+}
+/**
+ * Task concern handlers (squad_*_issue).
+ */
+export interface TaskHandlers extends HandlerLifecycle {
+    squad_create_issue?: SkillHandler<CreateIssueArgs>;
+    squad_update_issue?: SkillHandler<UpdateIssueArgs>;
+    squad_list_issues?: SkillHandler<ListIssuesArgs>;
+    squad_close_issue?: SkillHandler<CloseIssueArgs>;
+}
+/**
+ * Decision concern handlers (squad_*_decision).
+ */
+export interface DecisionHandlers extends HandlerLifecycle {
+    squad_create_decision?: SkillHandler<CreateDecisionArgs>;
+    squad_list_decisions?: SkillHandler<ListDecisionsArgs>;
+    squad_merge_decision?: SkillHandler<MergeDecisionArgs>;
+}
+/**
+ * Memory concern handlers (squad_*_memory).
+ */
+export interface MemoryHandlers extends HandlerLifecycle {
+    squad_create_memory?: SkillHandler<CreateMemoryArgs>;
+    squad_list_memories?: SkillHandler<ListMemoriesArgs>;
+}
+/**
+ * Logging concern handlers (squad_*_log).
+ */
+export interface LogHandlers extends HandlerLifecycle {
+    squad_create_log?: SkillHandler<CreateLogArgs>;
+    squad_list_logs?: SkillHandler<ListLogsArgs>;
+}
+/**
+ * Union of all handler interfaces.
+ */
+export type AllHandlers = TaskHandlers & DecisionHandlers & MemoryHandlers & LogHandlers;
+/**
+ * Strip HandlerLifecycle keys, keep only tool-name keys.
+ */
+type OwnKeys<T> = Exclude<keyof T, keyof HandlerLifecycle>;
+/**
+ * true if A and B share no tool-name keys; never otherwise.
+ */
+type AssertDisjoint<A, B> = Extract<OwnKeys<A>, OwnKeys<B>> extends never ? true : never;
+export type _TaskDecision = AssertDisjoint<TaskHandlers, DecisionHandlers>;
+export type _TaskMemory = AssertDisjoint<TaskHandlers, MemoryHandlers>;
+export type _TaskLog = AssertDisjoint<TaskHandlers, LogHandlers>;
+export type _DecisionMemory = AssertDisjoint<DecisionHandlers, MemoryHandlers>;
+export type _DecisionLog = AssertDisjoint<DecisionHandlers, LogHandlers>;
+export type _MemoryLog = AssertDisjoint<MemoryHandlers, LogHandlers>;
+/**
+ * Maps concern names to their handler interfaces.
+ */
+export interface ConcernMap {
+    tasks: TaskHandlers;
+    decisions: DecisionHandlers;
+    memories: MemoryHandlers;
+    logging: LogHandlers;
+}
+/**
+ * Valid concern names.
+ */
+export type Concern = keyof ConcernMap;
+/**
+ * Return type for SkillScriptLoader.load().
+ */
+export interface LoadResult {
+    /**
+     * Fully-formed SquadTool entries — skill handlers combined with built-in schemas.
+     */
+    tools: SquadTool[];
+    /**
+     * Lifecycle hooks from scripts/lifecycle.js, if present.
+     */
+    lifecycle?: {
+        init?(config: Record<string, unknown>): Promise<void>;
+        dispose?(): Promise<void>;
+    };
+}
+/**
+ * Skill configuration entry.
+ *
+ * Specifies a skill directory path and optional disposal timeout.
+ * The 'package' key is reserved for future use and forbidden here.
+ *
+ * @warning **Security note:** `backendConfig` is for non-secret runtime configuration (URLs, feature
+   * flags, timeouts). Do NOT put credentials, tokens, or secrets in `backendConfig` — this config is
+   * part of the skill definition and will be committed to the repository. Handler scripts run with full
+   * process trust and can access the filesystem and the network. Only load skills from trusted sources.
+ */
+export interface SkillConfig {
+    /** Path to skill directory (relative to squad root) */
+    skill: string;
+    /** Prevent future package key coexisting with skill */
+    package?: never;
+    /** Timeout for dispose() in ms (default: 10000) */
+    disposeTimeoutMs?: number;
+    [key: string]: unknown;
+}
+/**
+ * A reference to a backend:
+ * - undefined → built-in markdown (default)
+ * - "markdown" → built-in markdown (explicit reset)
+ * - "noop" → silent no-op (disables the concern)
+ * - { skill, ...opts } → skill directory with config options
+ */
+export type BackendRef = "markdown" | "noop" | SkillConfig;
+/**
+ * Direct handler registration (alternative to skill path).
+ * Used for programmatically-provided handlers.
+ */
+export interface HandlerRegistration<H extends HandlerLifecycle> {
+    handlers: H;
+}
+/**
+ * Tracking configuration for backend skills.
+ *
+ * Controls which backend (markdown, noop, or skill) serves each concern.
+ * Supports a global default with per-concern overrides.
+ */
+export interface TrackingConfig {
+    /** Backend for ALL concerns unless individually overridden */
+    default?: BackendRef;
+    decisions?: BackendRef | HandlerRegistration<DecisionHandlers>;
+    memories?: BackendRef | HandlerRegistration<MemoryHandlers>;
+    tasks?: BackendRef | HandlerRegistration<TaskHandlers>;
+    logging?: BackendRef | HandlerRegistration<LogHandlers>;
+}
+/**
+ * Identity function for type inference in handler scripts.
+ *
+ * Provides compile-time safety when authoring TypeScript handlers.
+ * The compiled .js output is a plain function — no runtime dependency on this.
+ *
+ * @example
+ * ```typescript
+ * export default defineHandler<CreateIssueArgs>(async (args, config) => {
+ *   return { type: "success", text: `Issue created: ${args.title}` };
+ * });
+ * ```
+ */
+export declare function defineHandler<TArgs = unknown>(handler: SkillHandler<TArgs>): SkillHandler<TArgs>;
+export {};
+//# sourceMappingURL=handler-types.d.ts.map

package/dist/skills/handler-types.d.ts.map

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

package/dist/skills/handler-types.js

@@ -0,0 +1,31 @@
+/**
+ * Type system for the skill-script model.
+ *
+ * This module defines the complete type contract for backend skills in `.copilot/skills/`.
+ * Skills contain `scripts/` directories with executable JS handlers that replace built-in
+ * tool handlers in ToolRegistry.
+ *
+ * The skill-script model enables stateful, framework-aware backends for tasks, decisions,
+ * memories, and logging concerns. Handlers are ordinary async functions that return
+ * SquadToolResult values.
+ */
+// Compile fails if any pair shares a tool name:
+const _disjointProof = [true, true, true, true, true, true];
+// ─── defineHandler Helper ────────────────────────────────────────────────────
+/**
+ * Identity function for type inference in handler scripts.
+ *
+ * Provides compile-time safety when authoring TypeScript handlers.
+ * The compiled .js output is a plain function — no runtime dependency on this.
+ *
+ * @example
+ * ```typescript
+ * export default defineHandler<CreateIssueArgs>(async (args, config) => {
+ *   return { type: "success", text: `Issue created: ${args.title}` };
+ * });
+ * ```
+ */
+export function defineHandler(handler) {
+    return handler;
+}
+//# sourceMappingURL=handler-types.js.map

package/dist/skills/handler-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-types.js","sourceRoot":"","sources":["../../src/skills/handler-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAgNH,gDAAgD;AAChD,MAAM,cAAc,GAOhB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AA8FzC,gFAAgF;AAEhF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAC3B,OAA4B;IAE5B,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/skills/index.d.ts

@@ -46,4 +46,7 @@ export declare class SkillRegistry {
      */
     loadSkill(skillId: string): string | undefined;
 }
+export * from './handler-types.js';
+export { SkillScriptLoader, resolveSkillPath } from './skill-script-loader.js';
+export type { LoadResult } from './handler-types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/skills/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/skills/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC9F,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,cAAc,mBAAmB,CAAC;AAIlC,MAAM,WAAW,UAAU;IACzB,wBAAwB;IACxB,KAAK,EAAE,eAAe,CAAC;IACvB,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAA2C;IAEzD,mCAAmC;IACnC,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAI3C,gCAAgC;IAChC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIzC,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAItD,iCAAiC;IACjC,YAAY,IAAI,eAAe,EAAE;IAIjC,mCAAmC;IACnC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;;;OASG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,EAAE;IA0C1D;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAG/C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/skills/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC9F,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,cAAc,mBAAmB,CAAC;AAIlC,MAAM,WAAW,UAAU;IACzB,wBAAwB;IACxB,KAAK,EAAE,eAAe,CAAC;IACvB,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAA2C;IAEzD,mCAAmC;IACnC,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAI3C,gCAAgC;IAChC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIzC,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAItD,iCAAiC;IACjC,YAAY,IAAI,eAAe,EAAE;IAIjC,mCAAmC;IACnC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;;;OASG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,EAAE;IA0C1D;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAG/C;AAID,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/skills/index.js

@@ -82,4 +82,7 @@ export class SkillRegistry {
         return this.skills.get(skillId)?.content;
     }
 }
+// --- Skill Script System Exports ---
+export * from './handler-types.js';
+export { SkillScriptLoader, resolveSkillPath } from './skill-script-loader.js';
 //# sourceMappingURL=index.js.map

package/dist/skills/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/skills/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/skills/index.ts"],"names":[],"mappings":"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"}

package/dist/skills/skill-script-loader.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Skill Script Loader
+ *
+ * Runtime loader for executable skill handlers from backend skill directories.
+ * Backend skills in `.copilot/skills/{name}/scripts/` contain `.js` handler files
+ * that replace built-in tool handlers in ToolRegistry.
+ *
+ * Supports:
+ * - Loading concern-specific handler scripts (tasks, decisions, memories, logging)
+ * - Dynamic import() of handler scripts with lifecycle hooks
+ * - Path containment validation for security
+ * - Partial implementations (missing handlers are silently skipped)
+ */
+import type { LoadResult } from './handler-types.js';
+/**
+ * Resolve a skill path relative to project/team roots with containment validation.
+ *
+ * Algorithm:
+ * 1. Absolute paths used as-is
+ * 2. With teamRoot: resolve `.copilot/` paths from projectRoot and strip legacy `.squad/` paths relative to teamRoot
+ * 3. Without teamRoot: resolve relative to projectRoot
+ * 4. Path containment check: final path must be within projectRoot or teamRoot
+ * 5. Reject paths with `..` segments that escape the boundary (throw Error)
+ *
+ * @param skillPath - Path from skill configuration (absolute or relative)
+ * @param projectRoot - Project root directory (absolute)
+ * @param teamRoot - Team root directory (absolute, optional)
+ * @returns Resolved absolute path
+ * @throws Error if path escapes containment boundaries
+ */
+export declare function resolveSkillPath(skillPath: string, projectRoot: string, teamRoot?: string): string;
+export declare class SkillScriptLoader {
+    private getToolSchema;
+    constructor(getToolSchema: (toolName: string) => {
+        description: string;
+        parameters: Record<string, unknown>;
+    } | undefined);
+    /**
+     * Load handler scripts from a backend skill directory by scanning `scripts/` for `.js` files.
+     *
+     * Algorithm:
+     * 1. Check for `scripts/` directory — return null if missing (triggers markdown fallback)
+     * 2. Scan scripts/ for all .js files (excluding lifecycle.js)
+     * 3. For each file, derive tool name: prepend 'squad_' to the filename stem
+     *    a. import() the script using toFileUrl (with Windows path normalization)
+     *    b. Validate: module.default must be a function — if not, THROW (not silent skip)
+     *    c. Get the tool's schema via this.getToolSchema(toolName)
+     *    d. If schema not found → skip with warning (tool not registered in ToolRegistry)
+     *    e. Produce a SquadTool entry with wrapSkillHandler()
+     * 4. Load scripts/lifecycle.js if present (import() it)
+     *    Extract init and dispose named exports if they are functions
+     * 5. Return { tools, lifecycle } or { tools } if no lifecycle
+     *
+     * @param skillPath - Resolved absolute path to the skill directory
+     * @param backendConfig - Backend configuration to pass to handlers
+     * @returns LoadResult with tools and optional lifecycle, or null if no scripts/ directory
+     *
+     * @warning **Security note:** `backendConfig` is for non-secret runtime configuration (URLs, feature
+     * flags, timeouts). Do NOT put credentials, tokens, or secrets in `backendConfig` — this config is
+     * part of the skill definition and will be committed to the repository. Handler scripts run with full
+     * process trust and can access the filesystem and the network. Only load skills from trusted sources.
+     */
+    load(skillPath: string, backendConfig: Record<string, unknown>): Promise<LoadResult | null>;
+}
+//# sourceMappingURL=skill-script-loader.d.ts.map

package/dist/skills/skill-script-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-script-loader.d.ts","sourceRoot":"","sources":["../../src/skills/skill-script-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EACV,UAAU,EAGX,MAAM,oBAAoB,CAAC;AA6D5B;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CA0CR;AAID,qBAAa,iBAAiB;IAE1B,OAAO,CAAC,aAAa;gBAAb,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,SAAS;IAGvH;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,IAAI,CACR,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;CA4E9B"}

package/dist/skills/skill-script-loader.js

@@ -0,0 +1,227 @@
+/**
+ * Skill Script Loader
+ *
+ * Runtime loader for executable skill handlers from backend skill directories.
+ * Backend skills in `.copilot/skills/{name}/scripts/` contain `.js` handler files
+ * that replace built-in tool handlers in ToolRegistry.
+ *
+ * Supports:
+ * - Loading concern-specific handler scripts (tasks, decisions, memories, logging)
+ * - Dynamic import() of handler scripts with lifecycle hooks
+ * - Path containment validation for security
+ * - Partial implementations (missing handlers are silently skipped)
+ */
+import { existsSync, readdirSync, realpathSync } from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { trace, SpanStatusCode } from '../runtime/otel-api.js';
+const tracer = trace.getTracer('squad-sdk');
+// --- OTel Handler Wrapping ---
+/**
+ * Wrap a skill handler with OTel span instrumentation.
+ * Mirrors the wrapping applied to built-in tools by defineTool() so skill-dispatched
+ * calls appear in traces, distinguished by 'tool.skill_dispatched: true'.
+ *
+ * This is intentionally a local copy — skill handlers and tool handlers have different
+ * signatures and concerns; they should not share implementation.
+ */
+function wrapSkillHandlerWithSpan(name, skillHandler, backendConfig) {
+    return async (args, _invocation) => {
+        const span = tracer.startSpan('squad.skill.call', {
+            attributes: { 'tool.name': name, 'tool.skill_dispatched': true },
+        });
+        const startTime = Date.now();
+        try {
+            const result = await skillHandler(args, backendConfig);
+            const durationMs = Date.now() - startTime;
+            span.addEvent('squad.skill.result', typeof result === 'string'
+                ? { 'result.type': 'unknown', 'result.length': result.length, 'duration_ms': durationMs, 'success': true }
+                : { 'result.type': result.resultType ?? 'unknown', 'result.length': (result.textResultForLlm ?? '').length, 'duration_ms': durationMs, 'success': result.resultType !== 'failure' });
+            return result;
+        }
+        catch (err) {
+            const durationMs = Date.now() - startTime;
+            span.setStatus({ code: SpanStatusCode.ERROR, message: err instanceof Error ? err.message : String(err) });
+            span.addEvent('squad.skill.error', {
+                'error.type': err instanceof Error ? err.constructor.name : 'unknown',
+                'error.message': err instanceof Error ? err.message : String(err),
+                'duration_ms': durationMs,
+            });
+            span.recordException(err instanceof Error ? err : new Error(String(err)));
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    };
+}
+// --- Helpers ---
+/**
+ * Normalize path separators for consistent module cache keys on Windows.
+ * pathToFileURL() can create different URLs from different path separator styles,
+ * leading to duplicate module instances. Always normalize before conversion.
+ */
+function toFileUrl(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    return pathToFileURL(normalized).href;
+}
+/**
+ * Resolve a skill path relative to project/team roots with containment validation.
+ *
+ * Algorithm:
+ * 1. Absolute paths used as-is
+ * 2. With teamRoot: resolve `.copilot/` paths from projectRoot and strip legacy `.squad/` paths relative to teamRoot
+ * 3. Without teamRoot: resolve relative to projectRoot
+ * 4. Path containment check: final path must be within projectRoot or teamRoot
+ * 5. Reject paths with `..` segments that escape the boundary (throw Error)
+ *
+ * @param skillPath - Path from skill configuration (absolute or relative)
+ * @param projectRoot - Project root directory (absolute)
+ * @param teamRoot - Team root directory (absolute, optional)
+ * @returns Resolved absolute path
+ * @throws Error if path escapes containment boundaries
+ */
+export function resolveSkillPath(skillPath, projectRoot, teamRoot) {
+    /** Resolve symlinks; fall back to the logical path if it doesn't exist yet (write case). */
+    function realOrLogical(p) {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return p;
+        }
+    }
+    /** True if `p` is equal to `root` or directly inside it. */
+    function isContained(p, root) {
+        const r = path.resolve(root);
+        return p === r || p.startsWith(r + path.sep);
+    }
+    // 1. Absolute paths used as-is
+    if (path.isAbsolute(skillPath)) {
+        const resolved = path.resolve(skillPath);
+        const real = realOrLogical(resolved);
+        const inside = (teamRoot ? isContained(real, teamRoot) || isContained(real, projectRoot) : isContained(real, projectRoot));
+        if (!inside)
+            throw new Error(`Path escapes containment: ${skillPath} is outside project and team roots`);
+        return resolved;
+    }
+    // 2. With teamRoot: resolve .copilot/ paths from projectRoot, legacy .squad/ paths from teamRoot
+    if (teamRoot) {
+        if (skillPath.startsWith('.copilot/')) {
+            const resolved = path.resolve(projectRoot, skillPath);
+            const real = realOrLogical(resolved);
+            if (!isContained(real, projectRoot))
+                throw new Error(`Path escapes containment: ${skillPath} resolves outside project root`);
+            return resolved;
+        }
+        const stripped = skillPath.startsWith('.squad/') ? skillPath.slice(7) : skillPath;
+        const resolved = path.resolve(teamRoot, stripped);
+        const real = realOrLogical(resolved);
+        if (!isContained(real, teamRoot))
+            throw new Error(`Path escapes containment: ${skillPath} resolves outside team root`);
+        return resolved;
+    }
+    // 3. Without teamRoot: resolve relative to projectRoot
+    const resolved = path.resolve(projectRoot, skillPath);
+    const real = realOrLogical(resolved);
+    if (!isContained(real, projectRoot))
+        throw new Error(`Path escapes containment: ${skillPath} resolves outside project root`);
+    return resolved;
+}
+// --- SkillScriptLoader ---
+export class SkillScriptLoader {
+    getToolSchema;
+    constructor(getToolSchema) {
+        this.getToolSchema = getToolSchema;
+    }
+    /**
+     * Load handler scripts from a backend skill directory by scanning `scripts/` for `.js` files.
+     *
+     * Algorithm:
+     * 1. Check for `scripts/` directory — return null if missing (triggers markdown fallback)
+     * 2. Scan scripts/ for all .js files (excluding lifecycle.js)
+     * 3. For each file, derive tool name: prepend 'squad_' to the filename stem
+     *    a. import() the script using toFileUrl (with Windows path normalization)
+     *    b. Validate: module.default must be a function — if not, THROW (not silent skip)
+     *    c. Get the tool's schema via this.getToolSchema(toolName)
+     *    d. If schema not found → skip with warning (tool not registered in ToolRegistry)
+     *    e. Produce a SquadTool entry with wrapSkillHandler()
+     * 4. Load scripts/lifecycle.js if present (import() it)
+     *    Extract init and dispose named exports if they are functions
+     * 5. Return { tools, lifecycle } or { tools } if no lifecycle
+     *
+     * @param skillPath - Resolved absolute path to the skill directory
+     * @param backendConfig - Backend configuration to pass to handlers
+     * @returns LoadResult with tools and optional lifecycle, or null if no scripts/ directory
+     *
+     * @warning **Security note:** `backendConfig` is for non-secret runtime configuration (URLs, feature
+     * flags, timeouts). Do NOT put credentials, tokens, or secrets in `backendConfig` — this config is
+     * part of the skill definition and will be committed to the repository. Handler scripts run with full
+     * process trust and can access the filesystem and the network. Only load skills from trusted sources.
+     */
+    async load(skillPath, backendConfig) {
+        // 1. Check for scripts/ directory
+        const scriptsDir = path.join(skillPath, 'scripts');
+        if (!existsSync(scriptsDir)) {
+            return null; // Triggers markdown fallback
+        }
+        // 2. Scan scripts/ for handler files — everything except lifecycle.js
+        const scriptFiles = readdirSync(scriptsDir).filter((f) => f.endsWith('.js') && f !== 'lifecycle.js');
+        const tools = [];
+        // 3. Load each discovered handler script
+        for (const scriptName of scriptFiles) {
+            // Derive tool name from filename: create_issue.js → squad_create_issue
+            const toolName = 'squad_' + scriptName.slice(0, -3);
+            const scriptPath = path.join(scriptsDir, scriptName);
+            // c. Get the tool's schema — outside the import try block so schema errors are attributed correctly
+            const schema = this.getToolSchema(toolName);
+            if (!schema) {
+                console.warn(`[SkillScriptLoader] Tool schema not found for ${toolName}, skipping`);
+                continue;
+            }
+            // d. Dynamic import — errors here mean the script itself is broken
+            try {
+                const scriptUrl = toFileUrl(scriptPath);
+                const module = await import(scriptUrl);
+                // b. Validate: module.default must be a function
+                if (typeof module.default !== 'function') {
+                    throw new Error(`Handler script ${scriptName} does not export a default function`);
+                }
+                // e. Create SquadTool entry — wrap with OTel span instrumentation at load time
+                // so skill-dispatched calls appear in traces with 'tool.skill_dispatched: true'.
+                const tool = {
+                    name: toolName,
+                    description: schema.description,
+                    parameters: schema.parameters,
+                    handler: wrapSkillHandlerWithSpan(toolName, module.default, backendConfig),
+                };
+                tools.push(tool);
+            }
+            catch (err) {
+                // Failed imports are fatal (validation errors, syntax errors, etc.)
+                throw new Error(`Failed to load handler script ${scriptName}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // 4. Load lifecycle.js if present
+        let lifecycle;
+        const lifecyclePath = path.join(scriptsDir, 'lifecycle.js');
+        if (existsSync(lifecyclePath)) {
+            try {
+                const lifecycleUrl = toFileUrl(lifecyclePath);
+                const lifecycleModule = await import(lifecycleUrl);
+                // Extract init and dispose named exports if they are functions
+                const init = typeof lifecycleModule.init === 'function' ? lifecycleModule.init : undefined;
+                const dispose = typeof lifecycleModule.dispose === 'function' ? lifecycleModule.dispose : undefined;
+                if (init || dispose) {
+                    lifecycle = { init, dispose };
+                }
+            }
+            catch (err) {
+                throw new Error(`Failed to load lifecycle.js: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // 5. Return result
+        return lifecycle ? { tools, lifecycle } : { tools };
+    }
+}
+//# sourceMappingURL=skill-script-loader.js.map