qlogicagent 0.1.0

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

@@ -0,0 +1,200 @@
+/**
+ * Parsed YAML frontmatter from a SKILL.md file.
+ * Keys are lowercased header names; values are always coerced to strings.
+ */
+export type ParsedSkillFrontmatter = Record<string, string>;
+/**
+ * A discovered skill on the filesystem.
+ */
+export interface WorkspaceSkill {
+    /** Display name (directory name by default). */
+    name: string;
+    /** One-line description extracted from frontmatter. */
+    description?: string;
+    /** Source tag for precedence/debugging, e.g. "bundled", "user", "project". */
+    source: string;
+    /** Absolute path to the SKILL.md file. */
+    filePath: string;
+    /** Absolute path to the skill directory (parent of SKILL.md). */
+    baseDir: string;
+    /** Primary runtime environment hint, e.g. "node", "python". */
+    primaryEnv?: string;
+    /** Environment variables the skill requires. */
+    requiredEnv?: string[];
+}
+/**
+ * Package-manager install specification for a skill dependency.
+ */
+export interface SkillInstallSpec {
+    id?: string;
+    kind: "brew" | "node" | "go" | "uv" | "download";
+    label?: string;
+    bins?: string[];
+    os?: string[];
+    formula?: string;
+    package?: string;
+    module?: string;
+    url?: string;
+    archive?: string;
+    extract?: boolean;
+    stripComponents?: number;
+    targetDir?: string;
+}
+/**
+ * Structured metadata from the `openclaw:` block inside SKILL.md frontmatter.
+ */
+export interface SkillMetadata {
+    /** If true, always include in prompt regardless of filter. */
+    always?: boolean;
+    /** Override key for deduplication / user-facing identification. */
+    skillKey?: string;
+    primaryEnv?: string;
+    emoji?: string;
+    homepage?: string;
+    /** Platform restriction: "win32", "darwin", "linux". */
+    os?: string[];
+    /** Use-case category for UI grouping. */
+    category?: string;
+    requires?: {
+        bins?: string[];
+        anyBins?: string[];
+        env?: string[];
+        config?: string[];
+    };
+    install?: SkillInstallSpec[];
+}
+/**
+ * Controls how a skill may be activated by user commands or model tool calls.
+ */
+export interface SkillInvocationPolicy {
+    /** Whether users can directly invoke this skill via slash-command. */
+    userInvocable: boolean;
+    /** If true, the model cannot trigger this skill autonomously. */
+    disableModelInvocation: boolean;
+}
+/**
+ * A fully resolved skill entry with parsed metadata.
+ */
+export interface SkillEntry {
+    skill: WorkspaceSkill;
+    frontmatter: ParsedSkillFrontmatter;
+    metadata?: SkillMetadata;
+    invocation?: SkillInvocationPolicy;
+}
+/**
+ * Slash-command dispatch specification for a skill.
+ */
+export interface SkillCommandDispatchSpec {
+    kind: "tool";
+    toolName: string;
+    argMode?: "raw";
+}
+/**
+ * A skill-derived slash-command for IM platforms.
+ */
+export interface SkillCommandSpec {
+    name: string;
+    skillName: string;
+    description: string;
+    dispatch?: SkillCommandDispatchSpec;
+}
+/**
+ * Serialized skill snapshot for system-prompt embedding.
+ */
+export interface SkillSnapshot {
+    prompt: string;
+    skills: Array<{
+        name: string;
+        primaryEnv?: string;
+        requiredEnv?: string[];
+    }>;
+    skillFilter?: string[];
+    version?: number;
+}
+export type SkillScanSeverity = "info" | "warn" | "critical";
+export interface SkillScanFinding {
+    ruleId: string;
+    severity: SkillScanSeverity;
+    file: string;
+    line: number;
+    message: string;
+    evidence: string;
+}
+export interface SkillScanSummary {
+    scannedFiles: number;
+    critical: number;
+    warn: number;
+    info: number;
+    findings: SkillScanFinding[];
+}
+export interface SkillScanOptions {
+    includeFiles?: string[];
+    maxFiles?: number;
+    maxFileBytes?: number;
+}
+/**
+ * Filesystem dependencies injected by the host runtime.
+ * Keeps the skill system decoupled from Node.js `fs` / `path`.
+ */
+export interface SkillFsDeps {
+    readFileSync(path: string, encoding: "utf-8"): string;
+    readFile(path: string, encoding: "utf-8"): Promise<string>;
+    existsSync(path: string): boolean;
+    statSync(path: string): {
+        size: number;
+        mtimeMs: number;
+        isDirectory(): boolean;
+    };
+    readdirSync(path: string, opts: {
+        withFileTypes: true;
+    }): Array<{
+        name: string;
+        isDirectory(): boolean;
+        isSymbolicLink(): boolean;
+    }>;
+    realpathSync(path: string): string;
+}
+export interface SkillPathDeps {
+    join(...segments: string[]): string;
+    resolve(...segments: string[]): string;
+    extname(p: string): string;
+    sep: string;
+}
+/**
+ * Configurable limits for skill discovery to prevent abuse.
+ */
+export interface SkillLoadLimits {
+    maxCandidatesPerRoot?: number;
+    maxSkillsLoadedPerSource?: number;
+    maxSkillsInPrompt?: number;
+    maxSkillsPromptChars?: number;
+    maxSkillFileBytes?: number;
+}
+/**
+ * Search paths for skill discovery, ordered by precedence (low → high).
+ */
+export interface SkillSearchPaths {
+    /** Bundled with npm package or app install. */
+    bundled?: string;
+    /** Extra directories from config. */
+    extra?: string[];
+    /** Managed skills (installed via CLI). */
+    managed?: string;
+    /** Personal agent skills: ~/.agents/skills/ */
+    personalAgents?: string;
+    /** Project agent skills: <workspace>/.agents/skills/ */
+    projectAgents?: string;
+    /** Workspace-level: <workspace>/skills/ */
+    workspace?: string;
+}
+/**
+ * Aggregate deps for the skill loader.
+ */
+export interface SkillLoaderDeps {
+    fs: SkillFsDeps;
+    path: SkillPathDeps;
+    homeDir: string;
+    searchPaths: SkillSearchPaths;
+    limits?: SkillLoadLimits;
+}
+//# sourceMappingURL=skill-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skill-types.d.ts","sourceRoot":"","sources":["../../src/skills/skill-types.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,UAAU,CAAC;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IACd,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC;IACF,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,aAAa,EAAE,OAAO,CAAC;IACvB,iEAAiE;IACjE,sBAAsB,EAAE,OAAO,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,cAAc,CAAC;IACtB,WAAW,EAAE,sBAAsB,CAAC;IACpC,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,KAAK,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,wBAAwB,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAC7E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAMD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3D,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,IAAI,OAAO,CAAA;KAAE,CAAC;IAClF,WAAW,CACT,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;QAAE,aAAa,EAAE,IAAI,CAAA;KAAE,GAC5B,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,IAAI,OAAO,CAAC;QAAC,cAAc,IAAI,OAAO,CAAA;KAAE,CAAC,CAAC;IAC9E,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IACpC,OAAO,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IACvC,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,WAAW,CAAC;IAChB,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B"}

package/dist/skills/skill-types.js

@@ -0,0 +1,7 @@
+// ---------------------------------------------------------------------------
+// Skill system type definitions — portable, runtime-agnostic.
+// Mirrors openclaw/src/agents/skills/types.ts + security/skill-scanner.ts
+// but decoupled from framework internals.
+// ---------------------------------------------------------------------------
+export {};
+//# sourceMappingURL=skill-types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skill-types.js","sourceRoot":"","sources":["../../src/skills/skill-types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,8DAA8D;AAC9D,0EAA0E;AAC1E,0CAA0C;AAC1C,8EAA8E"}

package/dist/skills/think-tool.d.ts

@@ -0,0 +1,17 @@
+import type { PortableTool } from "./portable-tool.js";
+export declare const THINK_TOOL_NAME: "think";
+export interface ThinkToolParams {
+    thought: string;
+}
+export declare const THINK_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly thought: {
+            readonly type: "string";
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["thought"];
+};
+export declare function createThinkTool(): PortableTool<ThinkToolParams>;
+//# sourceMappingURL=think-tool.d.ts.map

package/dist/skills/think-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"think-tool.d.ts","sourceRoot":"","sources":["../../src/skills/think-tool.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAsB,MAAM,oBAAoB,CAAC;AAE3E,eAAO,MAAM,eAAe,EAAG,OAAgB,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,iBAAiB;;;;;;;;;CAkBpB,CAAC;AAEX,wBAAgB,eAAe,IAAI,YAAY,CAAC,eAAe,CAAC,CAgC/D"}

package/dist/skills/think-tool.js

@@ -0,0 +1,60 @@
+// ============================================================
+// Think Tool — explicit reasoning before complex decisions.
+//
+// The Agent calls `think` to reason step-by-step before deciding
+// which tools to use. The thought is never shown to the user.
+// Pure no-op: zero side effects, zero dependencies.
+// ============================================================
+export const THINK_TOOL_NAME = "think";
+export const THINK_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        thought: {
+            type: "string",
+            description: [
+                "Your internal reasoning about the current situation.",
+                "Use this to:",
+                "• Analyze what the user really wants (disambiguate vague requests)",
+                "• Plan multi-step approaches before executing",
+                "• Evaluate which tool(s) to use and why",
+                "• Consider edge cases or potential issues",
+                "• Reflect on conversation context and user preferences",
+                "This content is never shown to the user.",
+            ].join("\n"),
+        },
+    },
+    required: ["thought"],
+};
+export function createThinkTool() {
+    return {
+        name: THINK_TOOL_NAME,
+        label: "Think",
+        shouldDefer: true,
+        description: [
+            "Use this tool to think and reason about the current situation BEFORE taking action.",
+            "Call this tool when you need to:",
+            "- Analyze an ambiguous or complex user request before deciding what to do",
+            "- Plan a multi-step approach (what tools to call and in what order)",
+            "- Identify which steps can run in parallel vs. which must be sequential",
+            "- Evaluate tradeoffs between different approaches",
+            "- Reflect on user preferences from conversation history",
+            "- Process new information that changes your understanding",
+            "",
+            "This tool has NO side effects — it simply records your reasoning process.",
+            "Your thought is NOT shown to the user; it only improves YOUR decision quality.",
+            "After thinking, proceed to take the appropriate action.",
+            "",
+            "When planning multi-step work, be explicit about parallelism:",
+            '- Say "这些可以并行生成" or "these can run in parallel" for independent tasks.',
+            '- Say "先…然后…" or "step 1 first, then step 2" for sequential dependencies.',
+        ].join("\n"),
+        parameters: THINK_TOOL_SCHEMA,
+        execute: async (_toolCallId, _params) => {
+            return {
+                content: [{ type: "text", text: "Thought recorded. Now proceed with the best action based on your reasoning." }],
+                details: { type: "think" },
+            };
+        },
+    };
+}
+//# sourceMappingURL=think-tool.js.map

package/dist/skills/think-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"think-tool.js","sourceRoot":"","sources":["../../src/skills/think-tool.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,4DAA4D;AAC5D,EAAE;AACF,iEAAiE;AACjE,8DAA8D;AAC9D,oDAAoD;AACpD,+DAA+D;AAI/D,MAAM,CAAC,MAAM,eAAe,GAAG,OAAgB,CAAC;AAMhD,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,IAAI,EAAE,QAAiB;IACvB,UAAU,EAAE;QACV,OAAO,EAAE;YACP,IAAI,EAAE,QAAiB;YACvB,WAAW,EAAE;gBACX,sDAAsD;gBACtD,cAAc;gBACd,oEAAoE;gBACpE,+CAA+C;gBAC/C,yCAAyC;gBACzC,2CAA2C;gBAC3C,wDAAwD;gBACxD,0CAA0C;aAC3C,CAAC,IAAI,CAAC,IAAI,CAAC;SACb;KACF;IACD,QAAQ,EAAE,CAAC,SAAS,CAAU;CACtB,CAAC;AAEX,MAAM,UAAU,eAAe;IAC7B,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,KAAK,EAAE,OAAO;QACd,WAAW,EAAE,IAAI;QACjB,WAAW,EAAE;YACX,qFAAqF;YACrF,kCAAkC;YAClC,2EAA2E;YAC3E,qEAAqE;YACrE,yEAAyE;YACzE,mDAAmD;YACnD,yDAAyD;YACzD,2DAA2D;YAC3D,EAAE;YACF,2EAA2E;YAC3E,gFAAgF;YAChF,yDAAyD;YACzD,EAAE;YACF,+DAA+D;YAC/D,wEAAwE;YACxE,2EAA2E;SAC5E,CAAC,IAAI,CAAC,IAAI,CAAC;QACZ,UAAU,EAAE,iBAAiB;QAE7B,OAAO,EAAE,KAAK,EAAE,WAAmB,EAAE,OAAwB,EAA+B,EAAE;YAC5F,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,6EAA6E,EAAE,CAAC;gBAChH,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;aAC3B,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/skills/todo-tool.d.ts

@@ -0,0 +1,64 @@
+import type { TodoItem } from "../contracts/todo.js";
+import type { PortableTool } from "./portable-tool.js";
+export declare const TODO_TOOL_NAME: "todo";
+export interface TodoToolParams {
+    todoList: TodoItem[];
+}
+export declare const TODO_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly todoList: {
+            readonly type: "array";
+            readonly description: string;
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "number";
+                        readonly description: "Unique numeric id (sequential from 1).";
+                    };
+                    readonly title: {
+                        readonly type: "string";
+                        readonly description: "Concise action-oriented label (3-7 words). Displayed in UI.";
+                    };
+                    readonly status: {
+                        readonly type: "string";
+                        readonly enum: readonly ["not-started", "in-progress", "completed"];
+                        readonly description: "not-started | in-progress (max 1) | completed";
+                    };
+                };
+                readonly required: readonly ["id", "title", "status"];
+            };
+        };
+    };
+    readonly required: readonly ["todoList"];
+};
+/**
+ * Configuration for todo tool behavior (CC-aligned features).
+ */
+export interface TodoToolOptions {
+    /**
+     * Unique agent/session identifier for per-agent todo isolation.
+     * When provided, different agents have independent todo lists.
+     */
+    agentId?: string;
+    /**
+     * Whether verification nudge is enabled.
+     * When all items are completed (≥3 items, none matching /verif/i),
+     * the tool signals that a verification sub-agent should be spawned.
+     */
+    enableVerificationNudge?: boolean;
+    /**
+     * Whether to auto-clear the list when all items are completed.
+     * Matches CC behavior: allDone → newTodos = [].
+     */
+    autoClearOnComplete?: boolean;
+}
+/**
+ * Create a stateful todo tool instance.
+ *
+ * Each call returns a tool with its own session-local list.
+ * Multiple instances can exist for different sessions/agents.
+ */
+export declare function createTodoTool(options?: TodoToolOptions): PortableTool<TodoToolParams>;
+//# sourceMappingURL=todo-tool.d.ts.map

package/dist/skills/todo-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo-tool.d.ts","sourceRoot":"","sources":["../../src/skills/todo-tool.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAAE,YAAY,EAAsB,MAAM,oBAAoB,CAAC;AAE3E,eAAO,MAAM,cAAc,EAAG,MAAe,CAAC;AAE9C,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,QAAQ,EAAE,CAAC;CACtB;AAED,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyBnB,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,YAAY,CAAC,cAAc,CAAC,CA4EtF"}

package/dist/skills/todo-tool.js

@@ -0,0 +1,115 @@
+// ============================================================
+// Todo Tool — session-level structured task management.
+//
+// Allows the agent to create, update, and track multi-step task
+// lists during complex conversations. Each tool invocation
+// replaces the full todo list (same pattern as Copilot's
+// manage_todo_list).
+//
+// Aligned with Claude Code TodoWriteTool:
+// - activeForm field (present-tense text for UI spinners)
+// - oldTodos snapshot returned for diffing
+// - Auto-clear when all items completed
+// - verificationNudgeNeeded signal
+// - Per-agent isolation via agentId option
+//
+// Reference: claude-code-haha/src/tools/TodoWriteTool/TodoWriteTool.ts
+// ============================================================
+import { summarizeTodoList } from "../contracts/todo.js";
+export const TODO_TOOL_NAME = "todo";
+export const TODO_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        todoList: {
+            type: "array",
+            description: "Complete array of ALL todo items. Must include both existing and new items. " +
+                "Only one item may be in-progress at a time. Mark todos completed " +
+                "IMMEDIATELY after finishing — do not batch completions.",
+            items: {
+                type: "object",
+                properties: {
+                    id: { type: "number", description: "Unique numeric id (sequential from 1)." },
+                    title: { type: "string", description: "Concise action-oriented label (3-7 words). Displayed in UI." },
+                    status: {
+                        type: "string",
+                        enum: ["not-started", "in-progress", "completed"],
+                        description: "not-started | in-progress (max 1) | completed",
+                    },
+                },
+                required: ["id", "title", "status"],
+            },
+        },
+    },
+    required: ["todoList"],
+};
+/**
+ * Create a stateful todo tool instance.
+ *
+ * Each call returns a tool with its own session-local list.
+ * Multiple instances can exist for different sessions/agents.
+ */
+export function createTodoTool(options) {
+    let currentList = [];
+    const opts = options ?? {};
+    return {
+        name: TODO_TOOL_NAME,
+        label: "Todo",
+        description: "Manage a structured todo list to track progress on multi-step tasks. " +
+            "Each call replaces the full list. Use frequently during complex work " +
+            "to plan steps and show progress. Mark items in-progress before starting, " +
+            "completed immediately after finishing.",
+        parameters: TODO_TOOL_SCHEMA,
+        searchHint: "manage session task checklist progress tracking",
+        maxResultSizeChars: 100_000,
+        execute: async (_toolCallId, params) => {
+            const items = params.todoList;
+            // Validate: at most 1 in-progress
+            const inProgress = items.filter((t) => t.status === "in-progress");
+            if (inProgress.length > 1) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({
+                                warning: `Only 1 item may be in-progress at a time (found ${inProgress.length}).`,
+                                todoList: currentList,
+                            }) }],
+                    details: { type: "todo", warning: "multiple_in_progress" },
+                };
+            }
+            // Capture old state for diff (CC-aligned: returns oldTodos)
+            const oldTodos = [...currentList];
+            // Check if all items are completed
+            const allDone = items.length > 0 && items.every((t) => t.status === "completed");
+            // Auto-clear when all completed (CC behavior)
+            if (allDone && opts.autoClearOnComplete) {
+                currentList = [];
+            }
+            else {
+                currentList = items;
+            }
+            const summary = summarizeTodoList(items);
+            // Verification nudge: ≥3 items, all done, none matching /verif/i
+            let verificationNudgeNeeded = false;
+            if (opts.enableVerificationNudge &&
+                allDone &&
+                items.length >= 3 &&
+                !items.some((t) => /verif/i.test(t.title))) {
+                verificationNudgeNeeded = true;
+            }
+            const result = {
+                total: summary.total,
+                completed: summary.completed,
+                inProgress: summary.inProgress,
+                notStarted: summary.notStarted,
+                todoList: currentList,
+                oldTodos,
+            };
+            if (verificationNudgeNeeded) {
+                result.verificationNudgeNeeded = true;
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(result) }],
+                details: { type: "todo", ...summary, verificationNudgeNeeded, agentId: opts.agentId },
+            };
+        },
+    };
+}
+//# sourceMappingURL=todo-tool.js.map

package/dist/skills/todo-tool.js.map

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

package/dist/skills/tools/agent-tool.d.ts

@@ -0,0 +1,92 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const AGENT_TOOL_NAME: "agent";
+/**
+ * Built-in agent types (CC-aligned registry).
+ * The LLM selects which agent to fork based on the task.
+ */
+export type BuiltInAgentType = "general" | "explore" | "plan" | "code" | "research" | "verify";
+export declare const BUILT_IN_AGENT_TYPES: BuiltInAgentType[];
+export interface AgentToolParams {
+    /** Built-in agent type to invoke. */
+    agent: BuiltInAgentType;
+    /** Detailed task prompt for the sub-agent. */
+    prompt: string;
+    /** Short description of the task (3-7 words). Used for status display. */
+    description?: string;
+    /** Max turns override (default varies by agent type). */
+    maxTurns?: number;
+    /** Run in background (returns task_id immediately). */
+    background?: boolean;
+}
+export declare const AGENT_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly agent: {
+            readonly type: "string";
+            readonly enum: readonly ["general", "explore", "plan", "code", "research", "verify"];
+            readonly description: string;
+        };
+        readonly prompt: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly description: {
+            readonly type: "string";
+            readonly description: "Short description (3-7 words) for status tracking.";
+        };
+        readonly maxTurns: {
+            readonly type: "number";
+            readonly description: "Max turns for the sub-agent. Defaults: general=200, explore=50, plan=80, code=200, research=30, verify=40.";
+        };
+        readonly background: {
+            readonly type: "boolean";
+            readonly description: "If true, runs in background and returns a task_id. Poll with task tool. Default: false.";
+        };
+    };
+    readonly required: readonly ["agent", "prompt"];
+    readonly additionalProperties: false;
+};
+export interface AgentResult {
+    agentId: string;
+    status: "completed" | "running" | "failed";
+    output?: string;
+    error?: string;
+    maxTurnsReached?: boolean;
+    tokensUsed?: number;
+}
+/**
+ * Host-provided fork execution backend (CC-aligned).
+ *
+ * Key properties of the fork mechanism:
+ * 1. Child shares parent's message prefix (prompt cache hit)
+ * 2. Child uses byte-identical prefix via placeholder results
+ * 3. Child has independent tool context (isolation)
+ * 4. Results flow back via in-memory streaming (not DB)
+ * 5. Fork depth tracked in-memory (max 4 layers)
+ */
+export interface AgentToolDeps {
+    /**
+     * Fork and run a sub-agent.
+     * The implementation must:
+     * - Share parent's rendered system prompt (byte-identical for cache)
+     * - Inherit parent's tool pool (filtered by agent definition)
+     * - Track fork depth (reject if > MAX_FORK_DEPTH)
+     * - Return output via in-memory streaming backflow
+     */
+    forkAgent(params: {
+        agent: BuiltInAgentType;
+        prompt: string;
+        description?: string;
+        maxTurns?: number;
+        background?: boolean;
+        abortSignal?: AbortSignal;
+    }): Promise<AgentResult>;
+    /** Abort signal from the parent turn. */
+    abortSignal?: AbortSignal;
+    /** Current fork depth (0 = root). Used for depth guard. */
+    currentForkDepth?: number;
+}
+/** Maximum fork depth for in-memory agents. */
+export declare const MAX_FORK_DEPTH = 4;
+export declare function createAgentTool(deps: AgentToolDeps): PortableTool<AgentToolParams>;
+//# sourceMappingURL=agent-tool.d.ts.map

package/dist/skills/tools/agent-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tool.d.ts","sourceRoot":"","sources":["../../../src/skills/tools/agent-tool.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,YAAY,EAAsB,MAAM,qBAAqB,CAAC;AAE5E,eAAO,MAAM,eAAe,EAAG,OAAgB,CAAC;AAEhD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE/F,eAAO,MAAM,oBAAoB,EAAE,gBAAgB,EAElD,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,KAAK,EAAE,gBAAgB,CAAC;IACxB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCpB,CAAC;AAEX,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;OAOG;IACH,SAAS,CAAC,MAAM,EAAE;QAChB,KAAK,EAAE,gBAAgB,CAAC;QACxB,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,WAAW,CAAC,EAAE,WAAW,CAAC;KAC3B,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEzB,yCAAyC;IACzC,WAAW,CAAC,EAAE,WAAW,CAAC;IAE1B,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,+CAA+C;AAC/C,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,YAAY,CAAC,eAAe,CAAC,CAmGlF"}