@vinhnt-sdk/core 0.1.0

package/dist/system-context/sources/instructions-source.js

@@ -0,0 +1,50 @@
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+export function createInstructionsSource(cwd) {
+    return {
+        key: "core.instructions",
+        priority: 10,
+        async load() {
+            const base = typeof cwd === "function" ? cwd() : (cwd ?? process.cwd());
+            const globalPath = resolve(process.env.HOME ?? process.env.USERPROFILE ?? "/root", ".opencode", "AGENTS.md");
+            const projectPath = resolve(base, "AGENTS.md");
+            const [global, project] = await Promise.all([
+                readIfExists(globalPath),
+                readIfExists(projectPath),
+            ]);
+            const parts = [];
+            if (global)
+                parts.push(`## Global Instructions\n${global}`);
+            if (project)
+                parts.push(`## Project Instructions\n${project}`);
+            const effective = parts.join("\n\n");
+            return { global, project, effective };
+        },
+        renderBaseline(value) {
+            if (!value.effective)
+                return "";
+            return value.effective;
+        },
+        renderUpdate(value, previous) {
+            if (value.effective === previous.effective)
+                return null;
+            return `[Context update — instructions changed]\n${value.effective || "No active instructions."}`;
+        },
+        renderRemoval() {
+            return "";
+        },
+    };
+}
+async function readIfExists(filePath) {
+    try {
+        if (existsSync(filePath)) {
+            return await readFile(filePath, "utf-8");
+        }
+    }
+    catch {
+        // ignore
+    }
+    return "";
+}
+//# sourceMappingURL=instructions-source.js.map

package/dist/system-context/sources/instructions-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions-source.js","sourceRoot":"","sources":["../../../src/system-context/sources/instructions-source.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,MAAM,UAAU,wBAAwB,CAAC,GAA6B;IACpE,OAAO;QACL,GAAG,EAAE,mBAAuC;QAC5C,QAAQ,EAAE,EAAE;QACZ,KAAK,CAAC,IAAI;YACR,MAAM,IAAI,GAAG,OAAO,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;YACxE,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,OAAO,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC;YAC7G,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAE/C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;gBAC1C,YAAY,CAAC,UAAU,CAAC;gBACxB,YAAY,CAAC,WAAW,CAAC;aAC1B,CAAC,CAAC;YAEH,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,IAAI,MAAM;gBAAE,KAAK,CAAC,IAAI,CAAC,2BAA2B,MAAM,EAAE,CAAC,CAAC;YAC5D,IAAI,OAAO;gBAAE,KAAK,CAAC,IAAI,CAAC,4BAA4B,OAAO,EAAE,CAAC,CAAC;YAC/D,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAErC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;QACxC,CAAC;QACD,cAAc,CAAC,KAAK;YAClB,IAAI,CAAC,KAAK,CAAC,SAAS;gBAAE,OAAO,EAAE,CAAC;YAChC,OAAO,KAAK,CAAC,SAAS,CAAC;QACzB,CAAC;QACD,YAAY,CAAC,KAAK,EAAE,QAAQ;YAC1B,IAAI,KAAK,CAAC,SAAS,KAAK,QAAQ,CAAC,SAAS;gBAAE,OAAO,IAAI,CAAC;YACxD,OAAO,4CAA4C,KAAK,CAAC,SAAS,IAAI,yBAAyB,EAAE,CAAC;QACpG,CAAC;QACD,aAAa;YACX,OAAO,EAAE,CAAC;QACZ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,QAAgB;IAC1C,IAAI,CAAC;QACH,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,OAAO,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,SAAS;IACX,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/system-context/sources/skill-guidance-source.d.ts

@@ -0,0 +1,7 @@
+import type { ContextSourceValue } from "../types.js";
+import type { SkillDefinition } from "@vinhnt-sdk/schema";
+export interface SkillGuidanceInfo {
+    skills: SkillDefinition[];
+}
+export declare function createSkillGuidanceSource(getSkills: () => SkillDefinition[]): ContextSourceValue<SkillGuidanceInfo>;
+//# sourceMappingURL=skill-guidance-source.d.ts.map

package/dist/system-context/sources/skill-guidance-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-guidance-source.d.ts","sourceRoot":"","sources":["../../../src/system-context/sources/skill-guidance-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAoB,MAAM,aAAa,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,eAAe,EAAE,GACjC,kBAAkB,CAAC,iBAAiB,CAAC,CA8BvC"}

package/dist/system-context/sources/skill-guidance-source.js

@@ -0,0 +1,41 @@
+export function createSkillGuidanceSource(getSkills) {
+    return {
+        key: "core.skills",
+        priority: 50,
+        async load() {
+            return { skills: getSkills() };
+        },
+        renderBaseline(value) {
+            const visible = value.skills.filter((s) => !s.manifest.hidden);
+            if (visible.length === 0)
+                return "";
+            const lines = ["<available_skills>"];
+            for (const skill of visible) {
+                lines.push(`  <skill>`);
+                lines.push(`    <name>${escapeXml(skill.manifest.name)}</name>`);
+                lines.push(`    <description>${escapeXml(skill.manifest.description)}</description>`);
+                if (skill.manifest.tools?.length) {
+                    lines.push(`    <tools>${skill.manifest.tools.join(", ")}</tools>`);
+                }
+                lines.push(`  </skill>`);
+            }
+            lines.push("</available_skills>");
+            return lines.join("\n");
+        },
+        renderUpdate() {
+            return null;
+        },
+        renderRemoval() {
+            return "";
+        },
+    };
+}
+function escapeXml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+//# sourceMappingURL=skill-guidance-source.js.map

package/dist/system-context/sources/skill-guidance-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-guidance-source.js","sourceRoot":"","sources":["../../../src/system-context/sources/skill-guidance-source.ts"],"names":[],"mappings":"AAOA,MAAM,UAAU,yBAAyB,CACvC,SAAkC;IAElC,OAAO;QACL,GAAG,EAAE,aAAiC;QACtC,QAAQ,EAAE,EAAE;QACZ,KAAK,CAAC,IAAI;YACR,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,CAAC;QACjC,CAAC;QACD,cAAc,CAAC,KAAK;YAClB,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC/D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,EAAE,CAAC;YACpC,MAAM,KAAK,GAAa,CAAC,oBAAoB,CAAC,CAAC;YAC/C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;gBACxB,KAAK,CAAC,IAAI,CAAC,aAAa,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBACjE,KAAK,CAAC,IAAI,CAAC,oBAAoB,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,gBAAgB,CAAC,CAAC;gBACtF,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;oBACjC,KAAK,CAAC,IAAI,CAAC,cAAc,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;gBACtE,CAAC;gBACD,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAC3B,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;YAClC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QACD,YAAY;YACV,OAAO,IAAI,CAAC;QACd,CAAC;QACD,aAAa;YACX,OAAO,EAAE,CAAC;QACZ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,CAAS;IAC1B,OAAO,CAAC;SACL,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;SACvB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC7B,CAAC"}

package/dist/system-context/sources/workspace-source.d.ts

@@ -0,0 +1,10 @@
+import type { ContextSourceValue } from "../types.js";
+export interface WorkspaceInfo {
+    cwd: string;
+    os: string;
+    arch: string;
+    nodeVersion: string;
+    shell: string;
+}
+export declare function createWorkspaceSource(cwd?: string | (() => string)): ContextSourceValue<WorkspaceInfo>;
+//# sourceMappingURL=workspace-source.d.ts.map

package/dist/system-context/sources/workspace-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-source.d.ts","sourceRoot":"","sources":["../../../src/system-context/sources/workspace-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAoB,MAAM,aAAa,CAAC;AAGxE,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,qBAAqB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,GAAG,kBAAkB,CAAC,aAAa,CAAC,CAyBtG"}

package/dist/system-context/sources/workspace-source.js

@@ -0,0 +1,29 @@
+import { arch, platform, release } from "node:os";
+export function createWorkspaceSource(cwd) {
+    return {
+        key: "core.workspace",
+        priority: 40,
+        async load() {
+            const root = typeof cwd === "function" ? cwd() : (cwd ?? process.cwd());
+            return {
+                cwd: root,
+                os: `${platform()} ${release()}`,
+                arch: arch(),
+                nodeVersion: process.version,
+                shell: process.env.SHELL ?? process.env.COMSPEC ?? "unknown",
+            };
+        },
+        renderBaseline(value) {
+            return `## Workspace\n- Working directory: \`${value.cwd}\`\n- OS: ${value.os} (${value.arch})\n- Node.js: ${value.nodeVersion}\n- Shell: ${value.shell}`;
+        },
+        renderUpdate(value, previous) {
+            if (value.cwd === previous.cwd)
+                return null;
+            return `[Context update — working directory changed]\nThe working directory is now \`${value.cwd}\`.`;
+        },
+        renderRemoval() {
+            return "";
+        },
+    };
+}
+//# sourceMappingURL=workspace-source.js.map

package/dist/system-context/sources/workspace-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-source.js","sourceRoot":"","sources":["../../../src/system-context/sources/workspace-source.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAUlD,MAAM,UAAU,qBAAqB,CAAC,GAA6B;IACjE,OAAO;QACL,GAAG,EAAE,gBAAoC;QACzC,QAAQ,EAAE,EAAE;QACZ,KAAK,CAAC,IAAI;YACR,MAAM,IAAI,GAAG,OAAO,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;YACxE,OAAO;gBACL,GAAG,EAAE,IAAI;gBACT,EAAE,EAAE,GAAG,QAAQ,EAAE,IAAI,OAAO,EAAE,EAAE;gBAChC,IAAI,EAAE,IAAI,EAAE;gBACZ,WAAW,EAAE,OAAO,CAAC,OAAO;gBAC5B,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,SAAS;aAC7D,CAAC;QACJ,CAAC;QACD,cAAc,CAAC,KAAK;YAClB,OAAO,wCAAwC,KAAK,CAAC,GAAG,aAAa,KAAK,CAAC,EAAE,KAAK,KAAK,CAAC,IAAI,iBAAiB,KAAK,CAAC,WAAW,cAAc,KAAK,CAAC,KAAK,EAAE,CAAC;QAC5J,CAAC;QACD,YAAY,CAAC,KAAK,EAAE,QAAQ;YAC1B,IAAI,KAAK,CAAC,GAAG,KAAK,QAAQ,CAAC,GAAG;gBAAE,OAAO,IAAI,CAAC;YAC5C,OAAO,gFAAgF,KAAK,CAAC,GAAG,KAAK,CAAC;QACxG,CAAC;QACD,aAAa;YACX,OAAO,EAAE,CAAC;QACZ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/system-context/types.d.ts

@@ -0,0 +1,37 @@
+export type ContextSourceKey = string & {
+    readonly __brand: unique symbol;
+};
+export interface ContextSnapshot {
+    readonly key: ContextSourceKey;
+    readonly value: unknown;
+    readonly rendered: string;
+}
+export interface SystemContext {
+    readonly baseline: string;
+    readonly snapshots: ReadonlyMap<ContextSourceKey, ContextSnapshot>;
+}
+export type ReconcileResult = {
+    readonly type: "unchanged";
+} | {
+    readonly type: "updated";
+    readonly update: string;
+    readonly snapshot: ContextSnapshot;
+} | {
+    readonly type: "replaced";
+    readonly systemContext: SystemContext;
+};
+export interface ContextRegistry {
+    register(source: ContextSourceValue): void;
+    unregister(key: ContextSourceKey): void;
+    initialize(): Promise<SystemContext>;
+    reconcile(): Promise<ReconcileResult>;
+}
+export interface ContextSourceValue<T = unknown> {
+    readonly key: ContextSourceKey;
+    readonly priority?: number;
+    load(): Promise<T>;
+    renderBaseline(value: T): string;
+    renderUpdate(value: T, previous: T): string | null;
+    renderRemoval(): string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/system-context/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/system-context/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,MAAM,CAAA;CAAE,CAAC;AAE5E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAC;CACpE;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;CAAE,GACzF;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAA;CAAE,CAAC;AAEzE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC3C,UAAU,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACxC,UAAU,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;IACrC,SAAS,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC,GAAG,OAAO;IAC7C,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IACnB,cAAc,CAAC,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC;IACjC,YAAY,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;IACnD,aAAa,IAAI,MAAM,CAAC;CACzB"}

package/dist/system-context/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/system-context/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/system-context/types.ts"],"names":[],"mappings":""}

package/dist/tool/arity.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Extract the "human-understandable command prefix" from shell tokens.
+ *
+ * Examples:
+ *   prefix(["npm", "install", "express", "--save"]) → ["npm", "install"]
+ *   prefix(["git", "checkout", "main"])             → ["git", "checkout"]
+ *   prefix(["docker", "compose", "up", "-d"])       → ["docker", "compose", "up"]
+ *   prefix(["cat", "file.txt"])                     → ["cat"]
+ *   prefix([])                                      → []
+ */
+export declare function prefix(tokens: string[]): string[];
+/**
+ * Convert a shell command string into a permission save pattern.
+ * The pattern with trailing " *" allows exact-match or prefix-match in saved rules.
+ *
+ * Examples:
+ *   commandPattern("npm install express --save") → "npm install *"
+ *   commandPattern("git checkout main")         → "git checkout *"
+ *   commandPattern("cat file.txt")              → "cat *"
+ */
+export declare function commandPattern(command: string): string;
+//# sourceMappingURL=arity.d.ts.map

package/dist/tool/arity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arity.d.ts","sourceRoot":"","sources":["../../src/tool/arity.ts"],"names":[],"mappings":"AAuEA;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAQjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAItD"}

package/dist/tool/arity.js

@@ -0,0 +1,96 @@
+/**
+ * ARITY dictionary: maps command prefixes to their "human-understandable" token count.
+ *
+ * When a user runs a command like "npm install express --save", the arity tells us
+ * that the meaningful prefix is ["npm", "install"] (arity 2). This enables:
+ * - Cleaner permission prompts ("Allow npm install?")
+ * - Smarter "always allow" patterns ("npm install *" matches any npm install variant)
+ */
+const ARITY = {
+    // Single-arity commands
+    cat: 1, cd: 1, chmod: 1, chown: 1, cp: 1, echo: 1, env: 1,
+    export: 1, git: 2, "git config": 3, "git remote": 3, "git stash": 3, grep: 1, kill: 1, killall: 1, ln: 1, ls: 1,
+    mkdir: 1, mv: 1, ps: 1, pwd: 1, rm: 1, rmdir: 1, sleep: 1,
+    source: 1, tail: 1, touch: 1, unset: 1, which: 1,
+    // Cloud / infrastructure
+    aws: 3, az: 3, gcloud: 3, gh: 3, doctl: 3, eksctl: 2,
+    "eksctl create": 3, cdk: 2, cf: 2, heroku: 2, vercel: 2,
+    pulumi: 2, "pulumi stack": 3, terraform: 2,
+    "terraform workspace": 3, vault: 2, "vault auth": 3,
+    "vault kv": 3, consul: 2, "consul kv": 3, nomad: 2,
+    serverless: 2, sls: 2, sst: 2, flyctl: 2, sfdx: 3,
+    // Containers / orchestration
+    docker: 2, "docker builder": 3, "docker compose": 3,
+    "docker container": 3, "docker image": 3, "docker network": 3,
+    "docker volume": 3, podman: 2, "podman container": 3,
+    "podman image": 3, kubectl: 2, "kubectl kustomize": 3,
+    "kubectl rollout": 3, kustomize: 2, helm: 2,
+    minikube: 2, kind: 2, "kind create": 3, crictl: 2,
+    skaffold: 2, compose: 2,
+    // Languages / runtimes
+    node: 2, python: 2, python3: 2, ruby: 2, rake: 2,
+    go: 2, cargo: 2, "cargo add": 3, "cargo run": 3,
+    rustup: 2, dotnet: 2, mvn: 2, gradle: 2, swift: 2,
+    deno: 2, "deno task": 3, bun: 2, "bun run": 3, "bun x": 3,
+    // JavaScript / Node ecosystem
+    npm: 2, "npm exec": 3, "npm init": 3, "npm run": 3,
+    "npm view": 3, npx: 2, yarn: 2, "yarn dlx": 3, "yarn run": 3,
+    pnpm: 2, "pnpm dlx": 3, "pnpm exec": 3, "pnpm run": 3,
+    nvm: 2, volta: 2, ng: 2, nx: 2, turbo: 2,
+    // Python
+    pip: 2, pip3: 2, pipenv: 2, poetry: 2, pyenv: 2,
+    // PHP
+    composer: 2, wp: 2,
+    // Databases
+    psql: 2, mysql: 2, mongosh: 2, "redis-cli": 2,
+    sqlite3: 2, pg_dump: 2, pg_restore: 2,
+    // Build tools
+    make: 2, cmake: 2, bazel: 2, meson: 2,
+    // System / network
+    systemctl: 2, journalctl: 2, ufw: 2, ip: 2, "ip addr": 3,
+    "ip link": 3, "ip netns": 3, "ip route": 3, tmux: 2,
+    screen: 2, openssl: 2, "openssl req": 3, "openssl x509": 3,
+    // Firestore / GCP
+    firebase: 2, gsutil: 2, bq: 2,
+    // Misc
+    brew: 2, "brew bundle": 3, "brew services": 3, mc: 2,
+    "mc admin": 3, vagrant: 2, packer: 2, sdkmanager: 2,
+    adb: 2, fastlane: 2, cocoapods: 2,
+};
+/**
+ * Extract the "human-understandable command prefix" from shell tokens.
+ *
+ * Examples:
+ *   prefix(["npm", "install", "express", "--save"]) → ["npm", "install"]
+ *   prefix(["git", "checkout", "main"])             → ["git", "checkout"]
+ *   prefix(["docker", "compose", "up", "-d"])       → ["docker", "compose", "up"]
+ *   prefix(["cat", "file.txt"])                     → ["cat"]
+ *   prefix([])                                      → []
+ */
+export function prefix(tokens) {
+    for (let len = tokens.length; len > 0; len--) {
+        const key = tokens.slice(0, len).join(" ");
+        const arity = ARITY[key];
+        if (arity !== undefined)
+            return tokens.slice(0, arity);
+    }
+    if (tokens.length === 0)
+        return [];
+    return tokens.slice(0, 1);
+}
+/**
+ * Convert a shell command string into a permission save pattern.
+ * The pattern with trailing " *" allows exact-match or prefix-match in saved rules.
+ *
+ * Examples:
+ *   commandPattern("npm install express --save") → "npm install *"
+ *   commandPattern("git checkout main")         → "git checkout *"
+ *   commandPattern("cat file.txt")              → "cat *"
+ */
+export function commandPattern(command) {
+    const tokens = command.trim().split(/\s+/);
+    if (tokens.length === 0 || (tokens.length === 1 && tokens[0] === ""))
+        return "*";
+    return prefix(tokens).join(" ") + " *";
+}
+//# sourceMappingURL=arity.js.map

package/dist/tool/arity.js.map

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

package/dist/tool/bridge.d.ts

@@ -0,0 +1,7 @@
+import type { PluginManager } from "../plugin.js";
+import type { ToolDefinition } from "./definitions.js";
+import { ToolRuntime, type ToolHook } from "./runtime.js";
+export declare function createKernelTools(rt: ToolRuntime): ToolDefinition[];
+/** Create a ToolHook that bridges PluginManager lifecycle hooks into the ToolRuntime pipeline */
+export declare function createPluginToolHook(pm: PluginManager): ToolHook;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/tool/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../src/tool/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAe,MAAM,kBAAkB,CAAC;AAEpE,OAAO,EAAE,WAAW,EAAE,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE1D,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,WAAW,GAAG,cAAc,EAAE,CAanE;AAED,iGAAiG;AACjG,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,aAAa,GAAG,QAAQ,CA2BhE"}

package/dist/tool/bridge.js

@@ -0,0 +1,48 @@
+import { ToolPermissionDenied } from "@vinhnt-sdk/schema";
+export function createKernelTools(rt) {
+    return rt.getTools().map((t) => ({
+        id: t.id,
+        description: t.description,
+        risk: t.risk,
+        inputSchema: t.inputSchema,
+        async execute(input, ctx) {
+            const result = await rt.execute(t.id, input, ctx);
+            if (result.status === "success")
+                return result.output;
+            if (result.status === "denied")
+                throw new ToolPermissionDenied(t.id, result.reason ?? "Permission denied");
+            throw new Error(result.error);
+        },
+    }));
+}
+/** Create a ToolHook that bridges PluginManager lifecycle hooks into the ToolRuntime pipeline */
+export function createPluginToolHook(pm) {
+    return {
+        id: "plugin-hooks",
+        async pre(params) {
+            const result = await pm.fireHook("onToolInvoked", {
+                toolId: params.toolId,
+                toolName: params.tool.id,
+                input: params.input,
+            });
+            if (result?.modified) {
+                return { input: result.modified.input };
+            }
+            return null;
+        },
+        async post(params) {
+            if (params.result.status === "error")
+                return null;
+            const result = await pm.fireHook("onToolCompleted", {
+                toolId: params.toolId,
+                toolName: params.tool.id,
+                output: params.result.status === "success" ? params.result.output : undefined,
+            });
+            if (result?.modified && params.result.status === "success") {
+                return { status: "success", output: result.modified.output };
+            }
+            return null;
+        },
+    };
+}
+//# sourceMappingURL=bridge.js.map

package/dist/tool/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../../src/tool/bridge.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAG1D,MAAM,UAAU,iBAAiB,CAAC,EAAe;IAC/C,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/B,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,KAAK,CAAC,OAAO,CAAC,KAAc,EAAE,GAAgB;YAC5C,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;YAClD,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;gBAAE,OAAO,MAAM,CAAC,MAAM,CAAC;YACtD,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ;gBAAE,MAAM,IAAI,oBAAoB,CAAC,CAAC,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,IAAI,mBAAmB,CAAC,CAAC;YAC3G,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;KACF,CAAC,CAAC,CAAC;AACN,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,oBAAoB,CAAC,EAAiB;IACpD,OAAO;QACL,EAAE,EAAE,cAAc;QAClB,KAAK,CAAC,GAAG,CAAC,MAAM;YACd,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,eAAe,EAAE;gBAChD,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE;gBACxB,KAAK,EAAE,MAAM,CAAC,KAAK;aACpB,CAAC,CAAC;YACH,IAAI,MAAM,EAAE,QAAQ,EAAE,CAAC;gBACrB,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;YAC1C,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,MAAM;YACf,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,OAAO;gBAAE,OAAO,IAAI,CAAC;YAClD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,iBAAiB,EAAE;gBAClD,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE;gBACxB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;aAC9E,CAAC,CAAC;YACH,IAAI,MAAM,EAAE,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC3D,OAAO,EAAE,MAAM,EAAE,SAAkB,EAAE,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;YACxE,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tool/context.d.ts

@@ -0,0 +1,43 @@
+/** Reply from human-in-the-loop approval */
+export type PermissionReply = "once" | "always" | "reject";
+import type { RequestContext } from "@vinhnt-sdk/schema";
+/** Context passed to every tool execution — replaces bare AbortSignal */
+export interface ToolContext {
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly agentId: string;
+    readonly agentName: string;
+    readonly signal: AbortSignal;
+    /**
+     * The parent run's request context (traceId/actorId/tenantId/requestId).
+     * Lets handoff tools (delegate/spawn) propagate identity + parent-run
+     * linkage to child agents instead of inventing a synthetic context.
+     */
+    readonly parentContext?: RequestContext;
+    /** Environment variables for subprocess execution (shell tool) */
+    readonly env: Record<string, string>;
+    /**
+     * Request human approval for a permission-bound operation.
+     * Returns the user's decision: "once" (allow once), "always" (approve forever), or "reject".
+     * When reply is "always", savePatterns are persisted as allow rules for future requests.
+     */
+    ask(input: {
+        permission: string;
+        resource: string;
+        reason: string;
+        /** Patterns to save as "always allow" rules if user replies "always". Uses arity-based truncation. */
+        savePatterns?: readonly string[];
+    }): Promise<PermissionReply>;
+    /** Attach metadata to the current tool call (for observability) */
+    metadata(input: {
+        title?: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+    /**
+     * Register a compensation action for saga rollback.
+     * If the current run fails or is cancelled, this action will be called
+     * to undo the tool's side effect (e.g., restore original file content).
+     */
+    setCompensation(action: () => Promise<void>): void;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/tool/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/tool/context.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,cAAc,CAAC;IAExC,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAErC;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE;QACT,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,sGAAsG;QACtG,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KAClC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAE7B,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GAAG,IAAI,CAAC;IAET;;;;OAIG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACpD"}

package/dist/tool/context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.js.map

package/dist/tool/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/tool/context.ts"],"names":[],"mappings":""}

package/dist/tool/define-tool.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolContext, ToolRisk } from "./definitions.js";
+import type { NestedJsonSchema } from "./json-schema.js";
+/**
+ * ── Schema-first tool authoring (OpenCode-style `Tool.make`) ──────────────
+ * The tool OWNS its validation schema (`input`) instead of importing a
+ * standalone static schema. `toDefinition()` derives the provider-facing
+ * `ToolDefinition` (JSON Schema) from that schema, so there is exactly one
+ * source of truth per tool. Domain namespacing is applied via `name`.
+ */
+export interface ToolConfig<TInput = unknown, TOutput = unknown> {
+    /** Tool name / id. Use dot-prefixed names for domains: "coding.read_file". */
+    name: string;
+    description: string;
+    risk: ToolRisk;
+    /** Runtime validation schema — owned by this tool, not a shared file. */
+    input: z.ZodType<TInput>;
+    /** Optional output validation schema. */
+    output?: z.ZodType<TOutput>;
+    /** Per-tool timeout in ms (overrides global default). */
+    timeoutMs?: number;
+    /** Permission action key for the gate (e.g. "edit", "shell"). Optional; defaults to risk. */
+    permissionAction?: string;
+    /** Optional LLM-facing JSON Schema override (e.g. to advertise `path` aliases). */
+    jsonSchema?: NestedJsonSchema;
+    /** Coerce raw model-agnostic input before validation (e.g. snake_case aliases). */
+    normalize?(raw: unknown): unknown;
+    execute(input: TInput, ctx: ToolContext): Promise<TOutput>;
+}
+export interface Tool<TInput = unknown, TOutput = unknown> {
+    readonly name: string;
+    readonly description: string;
+    readonly risk: ToolRisk;
+    readonly timeoutMs?: number;
+    readonly permissionAction?: string;
+    readonly input: z.ZodType<TInput>;
+    /** Derive the provider-facing ToolDefinition (registers as `name`). */
+    toDefinition(): ToolDefinition<TInput, TOutput>;
+}
+/** Map a Zod schema to the codebase's `NestedJsonSchema` shape (best effort). */
+export declare function zodSchemaToNestedJsonSchema(schema: z.ZodTypeAny): NestedJsonSchema | undefined;
+export declare function defineTool<TInput = unknown, TOutput = unknown>(config: ToolConfig<TInput, TOutput>): Tool<TInput, TOutput>;
+/** Convenience: build a ToolDefinition directly from a ToolConfig. */
+export declare function toolToDefinition<TInput = unknown, TOutput = unknown>(config: ToolConfig<TInput, TOutput>): ToolDefinition<TInput, TOutput>;
+//# sourceMappingURL=define-tool.d.ts.map

package/dist/tool/define-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-tool.d.ts","sourceRoot":"","sources":["../../src/tool/define-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD;;;;;;GAMG;AAEH,MAAM,WAAW,UAAU,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC7D,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,QAAQ,CAAC;IACf,yEAAyE;IACzE,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,yCAAyC;IACzC,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5B,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6FAA6F;IAC7F,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mFAAmF;IACnF,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,mFAAmF;IACnF,SAAS,CAAC,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC;IAClC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,uEAAuE;IACvE,YAAY,IAAI,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjD;AAID,iFAAiF;AACjF,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,gBAAgB,GAAG,SAAS,CAI9F;AAgFD,wBAAgB,UAAU,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAC5D,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CA8BvB;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAClE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAEjC"}