@galaxy-stack/ai-coder-core 0.1.0

package/dist/tools/tool-effect-profile.js

@@ -0,0 +1,157 @@
+/**
+ * Canonical host-effect policy for the built-in AI Coder tool catalog.
+ *
+ * Hosts must consume this profile instead of maintaining a local copy. The
+ * runtime treats these entries as a maximum authority boundary: a tool may
+ * omit an allowed effect, but it must never emit an effect absent here.
+ */
+import { compareAiCoderText } from "../deterministic-order.js";
+import { AI_CODER_CORE_TOOL_CATALOG } from "./tool-registry.js";
+const EFFECT_CAPABILITY_NAMES = [
+    "approval",
+    "criterion_satisfy",
+    "criterion_waive",
+    "diff_review",
+    "inspect",
+    "plan",
+    "research",
+    "state_version",
+    "validate",
+    "write",
+];
+export const AI_CODER_TOOL_EFFECT_CAPABILITIES = Object.freeze([...EFFECT_CAPABILITY_NAMES]);
+export const AI_CODER_CORE_TOOL_EFFECT_PROFILE_VERSION = "1.1.0";
+function effectCapabilities(...values) {
+    return Object.freeze([...values].sort(compareAiCoderText));
+}
+/**
+ * Exact effect capabilities for all 21 built-in tools. An empty or omitted
+ * effect is always valid; these arrays only describe effects a host may attest.
+ * Acceptance-criterion effects intentionally remain unavailable to built-in
+ * tools until a dedicated evidence-bearing contract is introduced.
+ */
+export const AI_CODER_CORE_TOOL_EFFECT_PROFILE = Object.freeze({
+    "artifact.create": effectCapabilities("approval", "state_version"),
+    "artifact.list": effectCapabilities("approval"),
+    "artifact.read": effectCapabilities("approval"),
+    "catalog.search": effectCapabilities("approval", "state_version"),
+    "command.run": effectCapabilities("approval", "state_version", "write"),
+    "command.session": effectCapabilities("approval", "state_version", "write"),
+    "git.exec": effectCapabilities("approval", "diff_review", "inspect"),
+    "perception.analyze": effectCapabilities("approval"),
+    "preview.manage": effectCapabilities("approval", "state_version"),
+    "project.detect": effectCapabilities("approval", "inspect"),
+    "project.validate": effectCapabilities("approval", "state_version", "validate", "write"),
+    "research.fetch": effectCapabilities("approval", "research"),
+    "research.search": effectCapabilities("approval", "research"),
+    "task.checkpoint": effectCapabilities("approval", "plan", "state_version"),
+    "user.ask": effectCapabilities("approval"),
+    "workspace.edit": effectCapabilities("approval", "state_version", "write"),
+    "workspace.glob": effectCapabilities("approval", "inspect"),
+    "workspace.grep": effectCapabilities("approval", "inspect"),
+    "workspace.list": effectCapabilities("approval", "inspect"),
+    "workspace.read": effectCapabilities("approval", "inspect"),
+    "workspace.write": effectCapabilities("approval", "state_version", "write"),
+});
+function ownEntry(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+/** Return every catalog/profile drift issue without throwing at the first one. */
+export function validateAiCoderCoreToolEffectProfile(input = {}) {
+    const descriptors = input.descriptors ?? AI_CODER_CORE_TOOL_CATALOG;
+    const profile = input.effectCapabilities ?? AI_CODER_CORE_TOOL_EFFECT_PROFILE;
+    const errors = [];
+    const allowed = new Set(AI_CODER_TOOL_EFFECT_CAPABILITIES);
+    const catalogIds = new Set();
+    const modelNames = new Set();
+    for (const descriptor of descriptors) {
+        if (!descriptor.id.trim())
+            errors.push("Catalog contains an empty canonical tool ID.");
+        else if (catalogIds.has(descriptor.id))
+            errors.push(`Duplicate canonical tool ID: ${descriptor.id}.`);
+        else
+            catalogIds.add(descriptor.id);
+        if (!descriptor.modelName.trim())
+            errors.push(`Tool ${descriptor.id || "<empty>"} has an empty model name.`);
+        else if (modelNames.has(descriptor.modelName))
+            errors.push(`Duplicate model-facing tool name: ${descriptor.modelName}.`);
+        else
+            modelNames.add(descriptor.modelName);
+    }
+    for (const id of [...catalogIds].sort(compareAiCoderText)) {
+        if (!ownEntry(profile, id))
+            errors.push(`Effect profile is missing core tool ${id}.`);
+    }
+    for (const id of Object.keys(profile).sort(compareAiCoderText)) {
+        if (!catalogIds.has(id))
+            errors.push(`Effect profile contains unknown core tool ${id}.`);
+        const values = profile[id];
+        if (!Array.isArray(values)) {
+            errors.push(`Effect profile for ${id} must be an array.`);
+            continue;
+        }
+        const normalized = [...new Set(values)].sort(compareAiCoderText);
+        if (normalized.length !== values.length)
+            errors.push(`Effect profile for ${id} contains duplicates.`);
+        if (normalized.some((value, index) => value !== values[index])) {
+            errors.push(`Effect profile for ${id} must use canonical deterministic order.`);
+        }
+        for (const value of values) {
+            if (!allowed.has(value))
+                errors.push(`Effect profile for ${id} contains unknown capability ${value}.`);
+        }
+    }
+    return Object.freeze(errors);
+}
+export function assertAiCoderCoreToolEffectProfile(input = {}) {
+    const errors = validateAiCoderCoreToolEffectProfile(input);
+    if (errors.length > 0)
+        throw new Error(`Invalid AI Coder core tool effect profile: ${errors.join(" ")}`);
+}
+/**
+ * Fail closed when a host changes the authority of a built-in tool. Unknown
+ * canonical IDs are extension/MCP tools and remain governed by the host's
+ * explicitly declared profile.
+ */
+export function assertAiCoderCoreToolEffectCapabilities(canonicalToolId, actual) {
+    const expected = AI_CODER_CORE_TOOL_EFFECT_PROFILE[canonicalToolId];
+    if (expected === undefined)
+        return;
+    const normalized = [...new Set(actual)].sort(compareAiCoderText);
+    if (normalized.length !== actual.length
+        || normalized.some((value, index) => value !== expected[index])
+        || normalized.length !== expected.length) {
+        throw new Error(`Core tool ${canonicalToolId} effect capabilities drifted; expected [${expected.join(", ")}], received [${actual.join(", ")}].`);
+    }
+}
+/**
+ * Build the exact active model-name mapping plus the complete stable effect
+ * policy expected by `AiCoderRuntimeToolSet`. Hosts should call this for the
+ * registry's active descriptors on every tool-set snapshot.
+ */
+export function createAiCoderCoreToolEffectMetadata(descriptors) {
+    const canonicalToolIds = {};
+    const seenIds = new Set();
+    for (const descriptor of [...descriptors].sort((left, right) => compareAiCoderText(left.id, right.id))) {
+        const capabilities = AI_CODER_CORE_TOOL_EFFECT_PROFILE[descriptor.id];
+        if (capabilities === undefined)
+            throw new Error(`No core effect profile exists for ${descriptor.id}.`);
+        if (seenIds.has(descriptor.id))
+            throw new Error(`Duplicate active canonical tool ID: ${descriptor.id}.`);
+        if (ownEntry(canonicalToolIds, descriptor.modelName)) {
+            throw new Error(`Duplicate active model-facing tool name: ${descriptor.modelName}.`);
+        }
+        seenIds.add(descriptor.id);
+        canonicalToolIds[descriptor.modelName] = descriptor.id;
+    }
+    return Object.freeze({
+        canonicalToolIds: Object.freeze(canonicalToolIds),
+        // Keep the complete profile stable across lazy tool activation. The
+        // runtime still limits invocation/result identity to canonicalToolIds.
+        effectCapabilities: AI_CODER_CORE_TOOL_EFFECT_PROFILE,
+    });
+}
+// A catalog/profile mismatch is a package construction error, not a condition
+// a host is allowed to recover from with a locally invented policy.
+assertAiCoderCoreToolEffectProfile();
+//# sourceMappingURL=tool-effect-profile.js.map

package/dist/tools/tool-effect-profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-effect-profile.js","sourceRoot":"","sources":["../../src/tools/tool-effect-profile.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAGhE,MAAM,uBAAuB,GAAG;IAC9B,UAAU;IACV,mBAAmB;IACnB,iBAAiB;IACjB,aAAa;IACb,SAAS;IACT,MAAM;IACN,UAAU;IACV,eAAe;IACf,UAAU;IACV,OAAO;CACC,CAAC;AAIX,MAAM,CAAC,MAAM,iCAAiC,GAA2C,MAAM,CAAC,MAAM,CACpG,CAAC,GAAG,uBAAuB,CAAC,CAC7B,CAAC;AAEF,MAAM,CAAC,MAAM,yCAAyC,GAAG,OAAO,CAAC;AAEjE,SAAS,kBAAkB,CACzB,GAAG,MAA8C;IAEjD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAE1C,MAAM,CAAC,MAAM,CAAC;IAChB,iBAAiB,EAAE,kBAAkB,CAAC,UAAU,EAAE,eAAe,CAAC;IAClE,eAAe,EAAE,kBAAkB,CAAC,UAAU,CAAC;IAC/C,eAAe,EAAE,kBAAkB,CAAC,UAAU,CAAC;IAC/C,gBAAgB,EAAE,kBAAkB,CAAC,UAAU,EAAE,eAAe,CAAC;IACjE,aAAa,EAAE,kBAAkB,CAAC,UAAU,EAAE,eAAe,EAAE,OAAO,CAAC;IACvE,iBAAiB,EAAE,kBAAkB,CAAC,UAAU,EAAE,eAAe,EAAE,OAAO,CAAC;IAC3E,UAAU,EAAE,kBAAkB,CAAC,UAAU,EAAE,aAAa,EAAE,SAAS,CAAC;IACpE,oBAAoB,EAAE,kBAAkB,CAAC,UAAU,CAAC;IACpD,gBAAgB,EAAE,kBAAkB,CAAC,UAAU,EAAE,eAAe,CAAC;IACjE,gBAAgB,EAAE,kBAAkB,CAAC,UAAU,EAAE,SAAS,CAAC;IAC3D,kBAAkB,EAAE,kBAAkB,CAAC,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,OAAO,CAAC;IACxF,gBAAgB,EAAE,kBAAkB,CAAC,UAAU,EAAE,UAAU,CAAC;IAC5D,iBAAiB,EAAE,kBAAkB,CAAC,UAAU,EAAE,UAAU,CAAC;IAC7D,iBAAiB,EAAE,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,eAAe,CAAC;IAC1E,UAAU,EAAE,kBAAkB,CAAC,UAAU,CAAC;IAC1C,gBAAgB,EAAE,kBAAkB,CAAC,UAAU,EAAE,eAAe,EAAE,OAAO,CAAC;IAC1E,gBAAgB,EAAE,kBAAkB,CAAC,UAAU,EAAE,SAAS,CAAC;IAC3D,gBAAgB,EAAE,kBAAkB,CAAC,UAAU,EAAE,SAAS,CAAC;IAC3D,gBAAgB,EAAE,kBAAkB,CAAC,UAAU,EAAE,SAAS,CAAC;IAC3D,gBAAgB,EAAE,kBAAkB,CAAC,UAAU,EAAE,SAAS,CAAC;IAC3D,iBAAiB,EAAE,kBAAkB,CAAC,UAAU,EAAE,eAAe,EAAE,OAAO,CAAC;CAC5E,CAAC,CAAC;AAYH,SAAS,QAAQ,CAAC,KAAwC,EAAE,GAAW;IACrE,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,oCAAoC,CAClD,QAA4B,EAAE;IAE9B,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,IAAI,0BAA0B,CAAC;IACpE,MAAM,OAAO,GAAG,KAAK,CAAC,kBAAkB,IAAI,iCAAiC,CAAC;IAC9E,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,iCAAiC,CAAC,CAAC;IACnE,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IAErC,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE;YAAE,MAAM,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;aAClF,IAAI,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,gCAAgC,UAAU,CAAC,EAAE,GAAG,CAAC,CAAC;;YACjG,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAEnC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,EAAE;YAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,UAAU,CAAC,EAAE,IAAI,SAAS,2BAA2B,CAAC,CAAC;aACxG,IAAI,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,qCAAqC,UAAU,CAAC,SAAS,GAAG,CAAC,CAAC;;YACpH,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC;QAC1D,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,uCAAuC,EAAE,GAAG,CAAC,CAAC;IACxF,CAAC;IACD,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC;QAC/D,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,6CAA6C,EAAE,GAAG,CAAC,CAAC;QACzF,MAAM,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC;QAC3B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,MAAM,CAAC,IAAI,CAAC,sBAAsB,EAAE,oBAAoB,CAAC,CAAC;YAC1D,SAAS;QACX,CAAC;QACD,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;QACjE,IAAI,UAAU,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;YAAE,MAAM,CAAC,IAAI,CAAC,sBAAsB,EAAE,uBAAuB,CAAC,CAAC;QACtG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YAC/D,MAAM,CAAC,IAAI,CAAC,sBAAsB,EAAE,0CAA0C,CAAC,CAAC;QAClF,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC;gBAAE,MAAM,CAAC,IAAI,CAAC,sBAAsB,EAAE,gCAAgC,KAAK,GAAG,CAAC,CAAC;QACzG,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,kCAAkC,CAAC,QAA4B,EAAE;IAC/E,MAAM,MAAM,GAAG,oCAAoC,CAAC,KAAK,CAAC,CAAC;IAC3D,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,8CAA8C,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAC3G,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uCAAuC,CACrD,eAAuB,EACvB,MAAyB;IAEzB,MAAM,QAAQ,GAAG,iCAAiC,CAAC,eAAe,CAAC,CAAC;IACpE,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO;IACnC,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;IACjE,IAAI,UAAU,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;WAClC,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,QAAQ,CAAC,KAAK,CAAC,CAAC;WAC5D,UAAU,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CACb,aAAa,eAAe,2CAA2C,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAChI,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mCAAmC,CACjD,WAAuE;IAEvE,MAAM,gBAAgB,GAA2B,EAAE,CAAC;IACpD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAElC,KAAK,MAAM,UAAU,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QACvG,MAAM,YAAY,GAAG,iCAAiC,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QACtE,IAAI,YAAY,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,UAAU,CAAC,EAAE,GAAG,CAAC,CAAC;QACvG,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,UAAU,CAAC,EAAE,GAAG,CAAC,CAAC;QACzG,IAAI,QAAQ,CAAC,gBAAgB,EAAE,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CAAC,4CAA4C,UAAU,CAAC,SAAS,GAAG,CAAC,CAAC;QACvF,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAC3B,gBAAgB,CAAC,UAAU,CAAC,SAAS,CAAC,GAAG,UAAU,CAAC,EAAE,CAAC;IACzD,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,gBAAgB,EAAE,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC;QACjD,oEAAoE;QACpE,uEAAuE;QACvE,kBAAkB,EAAE,iCAAiC;KACtD,CAAC,CAAC;AACL,CAAC;AAED,8EAA8E;AAC9E,oEAAoE;AACpE,kCAAkC,EAAE,CAAC"}

package/dist/tools/tool-registry-types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @author Bùi Trọng Hiếu
+ * @email kevinbui210191@gmail.com
+ * @create date 2026-08-21
+ * @modify date 2026-08-21
+ * @desc Tool descriptor shape used by the registry, router, and approval policy.
+ */
+import type { AiCoderTaskMode } from "../ports/execution-context.js";
+import type { AiCoderJsonSchema } from "./json-schema.js";
+export type AiCoderToolCategory = "artifact" | "bootstrap" | "command" | "communication" | "git" | "perception" | "preview" | "project" | "research" | "workspace";
+export type AiCoderToolModality = "text" | "image" | "video" | "audio" | "structured_data" | "artifact";
+export type AiCoderToolRisk = "low" | "medium" | "high" | "critical";
+export type AiCoderToolMutability = "read" | "write" | "execute" | "external_side_effect";
+export type AiCoderToolTransport = "native" | "core" | "extension" | "mcp";
+export type AiCoderToolIdempotency = "safe" | "with_key" | "unsafe";
+export type AiCoderToolRunMode = AiCoderTaskMode;
+export type AiCoderToolDescriptor = Readonly<{
+    category: AiCoderToolCategory;
+    description: string;
+    enabledByDefault: boolean;
+    id: string;
+    idempotency: AiCoderToolIdempotency;
+    inputSchema: AiCoderJsonSchema;
+    maxOutputBytes: number;
+    maxOutputTokens: number;
+    modalities: Readonly<{
+        accepts: readonly AiCoderToolModality[];
+        produces: readonly AiCoderToolModality[];
+        requiredModelCapabilities?: readonly string[];
+    }>;
+    modelName: string;
+    mutability: AiCoderToolMutability;
+    outputSchema: AiCoderJsonSchema;
+    permissions: readonly string[];
+    risk: AiCoderToolRisk;
+    source: Readonly<{
+        extensionId?: string;
+        owner: "base" | "core" | "extension" | "mcp";
+        serverId?: string;
+    }>;
+    supportsCancellation: boolean;
+    supportsPagination: boolean;
+    timeoutMs: number;
+    title: string;
+    transport: AiCoderToolTransport;
+    version: string;
+}>;
+export type AiCoderToolDiagnostic = Readonly<{
+    included: boolean;
+    reason: string;
+    toolId: string;
+    viaFallback?: string;
+}>;
+export type AiCoderToolRegistrySnapshot = Readonly<{
+    /** Hash of every descriptor visible after host capability, permission, and mode filtering. */
+    catalogHash: string;
+    descriptors: readonly AiCoderToolDescriptor[];
+    diagnostics: readonly AiCoderToolDiagnostic[];
+    /** @deprecated Use catalogHash. Kept for trace compatibility during the v2 migration. */
+    hash: string;
+    mode: AiCoderToolRunMode;
+    schemaVersion: string;
+}>;
+export type AiCoderActiveToolSnapshot = Readonly<{
+    /** Hash of the parent filtered catalog. */
+    catalogHash: string;
+    descriptors: readonly AiCoderToolDescriptor[];
+    /** Hash of the exact, canonically ordered tool definitions sent in one model turn. */
+    hash: string;
+    schemaVersion: string;
+}>;
+//# sourceMappingURL=tool-registry-types.d.ts.map

package/dist/tools/tool-registry-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry-types.d.ts","sourceRoot":"","sources":["../../src/tools/tool-registry-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,MAAM,MAAM,mBAAmB,GAC3B,UAAU,GACV,WAAW,GACX,SAAS,GACT,eAAe,GACf,KAAK,GACL,YAAY,GACZ,SAAS,GACT,SAAS,GACT,UAAU,GACV,WAAW,CAAC;AAEhB,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,iBAAiB,GAAG,UAAU,CAAC;AACxG,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AACrE,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,sBAAsB,CAAC;AAC1F,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,KAAK,CAAC;AAC3E,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,CAAC;AACpE,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAEjD,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,sBAAsB,CAAC;IACpC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,QAAQ,CAAC;QACnB,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;QACxC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;QACzC,yBAAyB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KAC/C,CAAC,CAAC;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,qBAAqB,CAAC;IAClC,YAAY,EAAE,iBAAiB,CAAC;IAChC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,QAAQ,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,KAAK,CAAC;QAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC,CAAC;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,oBAAoB,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC,CAAC;AAEH,MAAM,MAAM,2BAA2B,GAAG,QAAQ,CAAC;IACjD,8FAA8F;IAC9F,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC9C,WAAW,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC9C,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,kBAAkB,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC,CAAC;AAEH,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC9C,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC,CAAC"}

package/dist/tools/tool-registry-types.js

@@ -0,0 +1,9 @@
+/**
+ * @author Bùi Trọng Hiếu
+ * @email kevinbui210191@gmail.com
+ * @create date 2026-08-21
+ * @modify date 2026-08-21
+ * @desc Tool descriptor shape used by the registry, router, and approval policy.
+ */
+export {};
+//# sourceMappingURL=tool-registry-types.js.map

package/dist/tools/tool-registry-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry-types.js","sourceRoot":"","sources":["../../src/tools/tool-registry-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/tools/tool-registry.d.ts

@@ -0,0 +1,155 @@
+/**
+ * @author Bùi Trọng Hiếu
+ * @email kevinbui210191@gmail.com
+ * @create date 2026-08-21
+ * @modify date 2026-08-28
+ * @desc Canonical, immutable single-agent tool catalog and turn-scoped registry.
+ */
+import type { ModelCapabilities } from "../ports/capability-port.js";
+import type { CodingToolDefinition } from "./coding-messages.js";
+import { type AiCoderJsonSchema } from "./json-schema.js";
+import type { AiCoderActiveToolSnapshot, AiCoderToolDescriptor, AiCoderToolModality, AiCoderToolRegistrySnapshot, AiCoderToolRunMode } from "./tool-registry-types.js";
+export declare const AI_CODER_TOOL_REGISTRY_SCHEMA_VERSION = "2.0.0";
+export declare const AI_CODER_TOOL_DEFINITION_BUDGET = 10000;
+export type LegacyToolTarget = Readonly<{
+    kind: "galaxy-core" | "native";
+    name: string;
+}>;
+export declare const AI_CODER_CORE_TOOL_CATALOG: readonly AiCoderToolDescriptor[];
+export declare const AI_CODER_LEGACY_TOOL_TARGETS: Readonly<Record<string, LegacyToolTarget>>;
+export declare function isAiCoderToolAllowedInMode(tool: AiCoderToolDescriptor, mode: AiCoderToolRunMode): boolean;
+export declare function createAiCoderToolRegistrySnapshot(options: Readonly<{
+    availableToolIds: ReadonlySet<string>;
+    capabilities: ModelCapabilities;
+    descriptors?: readonly AiCoderToolDescriptor[];
+    grantedPermissions: ReadonlySet<string>;
+    mode?: AiCoderToolRunMode;
+}>): AiCoderToolRegistrySnapshot;
+export declare function descriptorToModelDefinition(tool: AiCoderToolDescriptor): CodingToolDefinition;
+export declare function estimateToolDefinitionTokens(definitions: readonly CodingToolDefinition[]): number;
+export declare class AiCoderToolRegistry {
+    readonly snapshot: AiCoderToolRegistrySnapshot;
+    private readonly activeIds;
+    private readonly byId;
+    private readonly byModelName;
+    constructor(snapshot: AiCoderToolRegistrySnapshot);
+    get activeDescriptors(): readonly Readonly<{
+        category: import("./tool-registry-types.js").AiCoderToolCategory;
+        description: string;
+        enabledByDefault: boolean;
+        id: string;
+        idempotency: import("./tool-registry-types.js").AiCoderToolIdempotency;
+        inputSchema: AiCoderJsonSchema;
+        maxOutputBytes: number;
+        maxOutputTokens: number;
+        modalities: Readonly<{
+            accepts: readonly AiCoderToolModality[];
+            produces: readonly AiCoderToolModality[];
+            requiredModelCapabilities?: readonly string[];
+        }>;
+        modelName: string;
+        mutability: import("./tool-registry-types.js").AiCoderToolMutability;
+        outputSchema: AiCoderJsonSchema;
+        permissions: readonly string[];
+        risk: import("./tool-registry-types.js").AiCoderToolRisk;
+        source: Readonly<{
+            extensionId?: string;
+            owner: "base" | "core" | "extension" | "mcp";
+            serverId?: string;
+        }>;
+        supportsCancellation: boolean;
+        supportsPagination: boolean;
+        timeoutMs: number;
+        title: string;
+        transport: import("./tool-registry-types.js").AiCoderToolTransport;
+        version: string;
+    }>[];
+    get definitions(): readonly Readonly<{
+        function: Readonly<{
+            description: string;
+            name: string;
+            parameters: Readonly<Record<string, unknown>>;
+        }>;
+        type: "function";
+    }>[];
+    get activeHash(): string;
+    get activeSnapshot(): AiCoderActiveToolSnapshot;
+    resolveModelName(modelName: string): Readonly<{
+        category: import("./tool-registry-types.js").AiCoderToolCategory;
+        description: string;
+        enabledByDefault: boolean;
+        id: string;
+        idempotency: import("./tool-registry-types.js").AiCoderToolIdempotency;
+        inputSchema: AiCoderJsonSchema;
+        maxOutputBytes: number;
+        maxOutputTokens: number;
+        modalities: Readonly<{
+            accepts: readonly AiCoderToolModality[];
+            produces: readonly AiCoderToolModality[];
+            requiredModelCapabilities?: readonly string[];
+        }>;
+        modelName: string;
+        mutability: import("./tool-registry-types.js").AiCoderToolMutability;
+        outputSchema: AiCoderJsonSchema;
+        permissions: readonly string[];
+        risk: import("./tool-registry-types.js").AiCoderToolRisk;
+        source: Readonly<{
+            extensionId?: string;
+            owner: "base" | "core" | "extension" | "mcp";
+            serverId?: string;
+        }>;
+        supportsCancellation: boolean;
+        supportsPagination: boolean;
+        timeoutMs: number;
+        title: string;
+        transport: import("./tool-registry-types.js").AiCoderToolTransport;
+        version: string;
+    }> | null;
+    resolveCanonicalId(toolId: string): Readonly<{
+        category: import("./tool-registry-types.js").AiCoderToolCategory;
+        description: string;
+        enabledByDefault: boolean;
+        id: string;
+        idempotency: import("./tool-registry-types.js").AiCoderToolIdempotency;
+        inputSchema: AiCoderJsonSchema;
+        maxOutputBytes: number;
+        maxOutputTokens: number;
+        modalities: Readonly<{
+            accepts: readonly AiCoderToolModality[];
+            produces: readonly AiCoderToolModality[];
+            requiredModelCapabilities?: readonly string[];
+        }>;
+        modelName: string;
+        mutability: import("./tool-registry-types.js").AiCoderToolMutability;
+        outputSchema: AiCoderJsonSchema;
+        permissions: readonly string[];
+        risk: import("./tool-registry-types.js").AiCoderToolRisk;
+        source: Readonly<{
+            extensionId?: string;
+            owner: "base" | "core" | "extension" | "mcp";
+            serverId?: string;
+        }>;
+        supportsCancellation: boolean;
+        supportsPagination: boolean;
+        timeoutMs: number;
+        title: string;
+        transport: import("./tool-registry-types.js").AiCoderToolTransport;
+        version: string;
+    }> | null;
+    activate(toolId: string): boolean;
+    search(query: string, category?: string, limit?: number, cursor?: string): {
+        catalogHash: string;
+        activeHash: string;
+        nextCursor?: string;
+        matches: {
+            id: string;
+            modelName: string;
+            title: string;
+            category: import("./tool-registry-types.js").AiCoderToolCategory;
+            active: boolean;
+        }[];
+        activated: string[];
+    };
+    private assertDefinitionBudget;
+}
+//# sourceMappingURL=tool-registry.d.ts.map

package/dist/tools/tool-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../src/tools/tool-registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAErE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EACV,yBAAyB,EACzB,qBAAqB,EAErB,mBAAmB,EACnB,2BAA2B,EAC3B,kBAAkB,EACnB,MAAM,0BAA0B,CAAC;AAGlC,eAAO,MAAM,qCAAqC,UAAU,CAAC;AAC7D,eAAO,MAAM,+BAA+B,QAAS,CAAC;AAEtD,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,IAAI,EAAE,aAAa,GAAG,QAAQ,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,CAAC;AAqVH,eAAO,MAAM,0BAA0B,EAAE,SAAS,qBAAqB,EAEtE,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAsBlF,CAAC;AAwFH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,kBAAkB,WAO/F;AASD,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,QAAQ,CAAC;IAChB,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtC,YAAY,EAAE,iBAAiB,CAAC;IAChC,WAAW,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC/C,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACxC,IAAI,CAAC,EAAE,kBAAkB,CAAC;CAC3B,CAAC,GACD,2BAA2B,CAiD7B;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,qBAAqB,GAAG,oBAAoB,CAS7F;AAED,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,SAAS,oBAAoB,EAAE,UAExF;AAED,qBAAa,mBAAmB;IAKlB,QAAQ,CAAC,QAAQ,EAAE,2BAA2B;IAJ1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6C;IAClE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6C;gBAEpD,QAAQ,EAAE,2BAA2B;IAO1D,IAAI,iBAAiB;;;;;;;;;;;;qCAniBlB,CAAC;;;;;;;;uBAImC,CAAC;;oBAMlB,CAAC;;;;;;;;SA8hBtB;IAED,IAAI,WAAW;;;;;;;SAEd;IAED,IAAI,UAAU,WAMb;IAED,IAAI,cAAc,IAAI,yBAAyB,CAO9C;IAED,gBAAgB,CAAC,SAAS,EAAE,MAAM;;;;;;;;;;;;qCA/jB/B,CAAC;;;;;;;;uBAImC,CAAC;;oBAMlB,CAAC;;;;;;;;;IA0jBvB,kBAAkB,CAAC,MAAM,EAAE,MAAM;;;;;;;;;;;;qCApkB9B,CAAC;;;;;;;;uBAImC,CAAC;;oBAMlB,CAAC;;;;;;;;;IA8jBvB,QAAQ,CAAC,MAAM,EAAE,MAAM;IAavB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,SAAI,EAAE,MAAM,CAAC,EAAE,MAAM;;;;;;;;;;;;;IAmCnE,OAAO,CAAC,sBAAsB;CAM/B"}