@try-works/dsh-model-as-tool 0.1.2 → 0.3.6

package/node_modules/@try-works/tool-mode-extension-sdk/lib/declarative-recipes.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Resolving a DECLARATIVE implementation's recipe (EXT-13, RCP-01, slice 3).
+ *
+ * THE CONVENTION THIS ESTABLISHES, and why it has to exist. The pinned manifest schema's
+ * `implementations` items permit only `id`, `contractId`, `contractVersion`, `modelId` and
+ * `recipeVersion`, with `additionalProperties: false` — so **a manifest cannot name its
+ * recipe files**. There is no path field to read.
+ *
+ * What a manifest declares is a recipe VERSION. The ARTEFACT is therefore located by a
+ * convention, and until now no convention existed because nothing had ever consumed a
+ * declarative manifest: every package in this repository was `kind: "module"` and reached its
+ * behaviour through a module entry.
+ *
+ * The convention, stated once so it is not re-invented at each call site:
+ *
+ *     <package>/recipes/<implementation-id>.json
+ *
+ * Chosen because the implementation id is already unique within the package, already matches
+ * `^[a-z][a-z0-9-]*$` by schema, and therefore needs no escaping or normalisation to become a
+ * file name. The alternative — keying on the contract id — would need path-mapping for the
+ * `tool-mode/` namespace and would collide when one contract has several implementations,
+ * which is exactly what `implementations` is an ARRAY to allow.
+ *
+ * @module @try-works/tool-mode-extension-sdk/declarative-recipes
+ */
+/** The directory the convention looks in. */
+export declare const RECIPE_DIRECTORY = "recipes";
+/** A resolved recipe, or the reason it could not be resolved. */
+export type RecipeResolution = {
+    readonly ok: true;
+    readonly recipe: unknown;
+    readonly path: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'missing' | 'unreadable' | 'invalid-json';
+    readonly path: string;
+    readonly detail: string;
+};
+/**
+ * Resolve one implementation's recipe by the convention.
+ *
+ * @param packageDir - the installed package root.
+ * @param implementationId - the manifest implementation id, which names the file.
+ * @returns the parsed recipe, or an honest failure.
+ */
+export declare function resolveDeclarativeRecipe(packageDir: string, implementationId: string): RecipeResolution;
+/**
+ * Resolve every implementation a declarative manifest declares.
+ *
+ * All-or-nothing on purpose: a package that could satisfy HALF its declarations would be
+ * activated in a state its manifest does not describe, and a caller would have no way to
+ * learn which half. Refusing names what is missing instead.
+ *
+ * @param packageDir - the installed package root.
+ * @param implementations - the manifest's declaration list.
+ * @returns every resolved recipe, or the first failure.
+ */
+export declare function resolveDeclarativeImplementations(packageDir: string, implementations: readonly {
+    readonly id: string;
+    readonly contractId: string;
+    readonly recipeVersion: string;
+}[]): {
+    readonly ok: true;
+    readonly resolved: readonly {
+        readonly id: string;
+        readonly contractId: string;
+        readonly recipeVersion: string;
+        readonly recipe: unknown;
+        readonly path: string;
+    }[];
+} | {
+    readonly ok: false;
+    readonly id: string;
+    readonly detail: string;
+};
+/**
+ * Whether an installed package is declarative, and what it declares.
+ *
+ * @param packageDir - the installed package root.
+ * @returns the declared recipe names when the package is declarative, else undefined.
+ */
+export declare function declaredRecipeNames(packageDir: string): readonly string[] | undefined;
+//# sourceMappingURL=declarative-recipes.d.ts.map

package/node_modules/@try-works/tool-mode-extension-sdk/lib/declarative-recipes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declarative-recipes.d.ts","sourceRoot":"","sources":["../src/declarative-recipes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,6CAA6C;AAC7C,eAAO,MAAM,gBAAgB,YAAY,CAAA;AAEzC,iEAAiE;AACjE,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,YAAY,GAAG,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtI;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,gBAAgB,CA6CvG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iCAAiC,CAC/C,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,SAAS;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE,EAAE,GAC/G;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAAE,GACzL;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAcvE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAQrF"}

package/node_modules/@try-works/tool-mode-extension-sdk/lib/declarative-recipes.js

@@ -0,0 +1,125 @@
+/**
+ * Resolving a DECLARATIVE implementation's recipe (EXT-13, RCP-01, slice 3).
+ *
+ * THE CONVENTION THIS ESTABLISHES, and why it has to exist. The pinned manifest schema's
+ * `implementations` items permit only `id`, `contractId`, `contractVersion`, `modelId` and
+ * `recipeVersion`, with `additionalProperties: false` — so **a manifest cannot name its
+ * recipe files**. There is no path field to read.
+ *
+ * What a manifest declares is a recipe VERSION. The ARTEFACT is therefore located by a
+ * convention, and until now no convention existed because nothing had ever consumed a
+ * declarative manifest: every package in this repository was `kind: "module"` and reached its
+ * behaviour through a module entry.
+ *
+ * The convention, stated once so it is not re-invented at each call site:
+ *
+ *     <package>/recipes/<implementation-id>.json
+ *
+ * Chosen because the implementation id is already unique within the package, already matches
+ * `^[a-z][a-z0-9-]*$` by schema, and therefore needs no escaping or normalisation to become a
+ * file name. The alternative — keying on the contract id — would need path-mapping for the
+ * `tool-mode/` namespace and would collide when one contract has several implementations,
+ * which is exactly what `implementations` is an ARRAY to allow.
+ *
+ * @module @try-works/tool-mode-extension-sdk/declarative-recipes
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/** The directory the convention looks in. */
+export const RECIPE_DIRECTORY = 'recipes';
+/**
+ * Resolve one implementation's recipe by the convention.
+ *
+ * @param packageDir - the installed package root.
+ * @param implementationId - the manifest implementation id, which names the file.
+ * @returns the parsed recipe, or an honest failure.
+ */
+export function resolveDeclarativeRecipe(packageDir, implementationId) {
+    const path = join(packageDir, RECIPE_DIRECTORY, `${implementationId}.json`);
+    /**
+     * The id is re-checked HERE rather than trusted from the manifest.
+     *
+     * The schema constrains it to `^[a-z][a-z0-9-]*$`, but this function builds a PATH from it,
+     * and a path built from an unvalidated string is a traversal. Re-checking costs nothing and
+     * means the resolver is safe even if a caller passes an id from somewhere the schema never
+     * saw — a hand-written manifest, a future protocol version, or a test.
+     */
+    if (!/^[a-z][a-z0-9-]*$/.test(implementationId)) {
+        return {
+            ok: false,
+            reason: 'missing',
+            path,
+            detail: `the implementation id ${JSON.stringify(implementationId)} is not a legal recipe name`,
+        };
+    }
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: 'missing',
+            path,
+            // The convention is NAMED in the failure, because a package author who put the file
+            // elsewhere can only fix it if they are told where it was looked for.
+            detail: `no recipe at ${RECIPE_DIRECTORY}/${implementationId}.json: `
+                + `${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    try {
+        return { ok: true, recipe: JSON.parse(text), path };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: 'invalid-json',
+            path,
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Resolve every implementation a declarative manifest declares.
+ *
+ * All-or-nothing on purpose: a package that could satisfy HALF its declarations would be
+ * activated in a state its manifest does not describe, and a caller would have no way to
+ * learn which half. Refusing names what is missing instead.
+ *
+ * @param packageDir - the installed package root.
+ * @param implementations - the manifest's declaration list.
+ * @returns every resolved recipe, or the first failure.
+ */
+export function resolveDeclarativeImplementations(packageDir, implementations) {
+    const resolved = [];
+    for (const implementation of implementations) {
+        const outcome = resolveDeclarativeRecipe(packageDir, implementation.id);
+        if (!outcome.ok)
+            return { ok: false, id: implementation.id, detail: outcome.detail };
+        resolved.push({
+            id: implementation.id,
+            contractId: implementation.contractId,
+            recipeVersion: implementation.recipeVersion,
+            recipe: outcome.recipe,
+            path: outcome.path,
+        });
+    }
+    return { ok: true, resolved };
+}
+/**
+ * Whether an installed package is declarative, and what it declares.
+ *
+ * @param packageDir - the installed package root.
+ * @returns the declared recipe names when the package is declarative, else undefined.
+ */
+export function declaredRecipeNames(packageDir) {
+    try {
+        const entries = readdirSync(join(packageDir, RECIPE_DIRECTORY));
+        return entries.filter(name => name.endsWith('.json')).map(name => name.slice(0, -'.json'.length)).sort();
+    }
+    catch {
+        // A package with no recipes directory is not declarative by this convention.
+        return undefined;
+    }
+}
+//# sourceMappingURL=declarative-recipes.js.map

package/node_modules/@try-works/tool-mode-extension-sdk/lib/discovery.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Bounded static discovery (EXT-13).
+ *
+ * Discovery reads a package as DATA and never imports it. That ordering is the
+ * security property, not an optimization: installation must not execute the
+ * package, so the host inspects `package.json` and the manifest, decides whether
+ * the package is acceptable, and only then considers running anything.
+ *
+ * Every read is bounded by a byte limit and every path is confined to the package
+ * directory, so a hostile package cannot make discovery read an arbitrary file or
+ * allocate without limit.
+ *
+ * @module @try-works/tool-mode-extension-sdk/discovery
+ */
+import { type LicenseLayer, type NoNetworkVerdict, type ResolvedLicenseRecord } from './licensing.ts';
+import { type ExtensionManifest } from './manifest.ts';
+/** Largest `package.json` accepted, in bytes. */
+export declare const MAX_PACKAGE_JSON_BYTES: number;
+/** What discovery learns about a package without running any of it. */
+export interface ExtensionDiscovery {
+    /** The package name from `package.json`. */
+    readonly packageName: string;
+    /** The package version from `package.json`. */
+    readonly packageVersion: string;
+    /** Absolute path of the unpacked package directory. */
+    readonly packageDir: string;
+    /** Absolute path of the manifest the `toolMode.manifest` field names. */
+    readonly manifestPath: string;
+    /**
+     * Absolute path of the public `./tool-mode` entry, resolved from the package's
+     * own `exports` map. Undefined for a declarative package, which has no module
+     * entry to import.
+     */
+    readonly entryPath?: string;
+    /** The validated manifest. */
+    readonly manifest: ExtensionManifest;
+    /**
+     * The resolved per-layer licence record (LIC-01).
+     *
+     * Produced by discovery rather than left to a consumer, so every caller resolves
+     * the same way and a package that declares no licences gets the same explicit gap
+     * report as one that declares an incomplete set.
+     */
+    readonly licenses: ResolvedLicenseRecord;
+    /** The layers the package did NOT declare, which are gaps rather than defaults. */
+    readonly licenseGaps: readonly LicenseLayer[];
+    /**
+     * Whether the package is eligible for a strict no-network deployment (LIC-04).
+     *
+     * Derived from the declaration, and a package that declares nothing is NOT
+     * eligible: silence about telemetry cannot be read as an absence of telemetry.
+     */
+    readonly noNetwork: NoNetworkVerdict;
+    /** How the package may truthfully describe its network behaviour. */
+    readonly networkDescription: string;
+    /** The declared public exports, which discovery requires to be explicit. */
+    readonly exports: readonly string[];
+}
+/**
+ * Discover an extension package without importing it.
+ *
+ * Enforces the EXT-13 package requirements: a `package.json` declaring `name`,
+ * `version`, `type: "module"`, an explicit `exports` map, and a `toolMode.manifest`
+ * field pointing at a manifest inside the package.
+ * @param packageDir - absolute path of the unpacked package.
+ * @returns the discovery result.
+ * @throws ManagementError with `INVALID_EXTENSION` for any violated requirement.
+ */
+export declare function discoverExtension(packageDir: string): ExtensionDiscovery;
+//# sourceMappingURL=discovery.d.ts.map

package/node_modules/@try-works/tool-mode-extension-sdk/lib/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAoE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAExH,iDAAiD;AACjD,eAAO,MAAM,sBAAsB,QAAa,CAAA;AAEhD,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAA;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAA;IACxC,mFAAmF;IACnF,QAAQ,CAAC,WAAW,EAAE,SAAS,YAAY,EAAE,CAAA;IAC7C;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAA;IACpC,qEAAqE;IACrE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;IACnC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AA0ED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,CAwJxE"}

package/node_modules/@try-works/tool-mode-extension-sdk/lib/discovery.js

@@ -0,0 +1,201 @@
+/**
+ * Bounded static discovery (EXT-13).
+ *
+ * Discovery reads a package as DATA and never imports it. That ordering is the
+ * security property, not an optimization: installation must not execute the
+ * package, so the host inspects `package.json` and the manifest, decides whether
+ * the package is acceptable, and only then considers running anything.
+ *
+ * Every read is bounded by a byte limit and every path is confined to the package
+ * directory, so a hostile package cannot make discovery read an arbitrary file or
+ * allocate without limit.
+ *
+ * @module @try-works/tool-mode-extension-sdk/discovery
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { ManagementError } from "./errors.js";
+import { describeNetwork, noNetworkEligibility, resolveLicenses, } from "./licensing.js";
+import { MAX_MANIFEST_BYTES, validateManifest, validateLockQualifications } from "./manifest.js";
+/** Largest `package.json` accepted, in bytes. */
+export const MAX_PACKAGE_JSON_BYTES = 256 * 1024;
+/**
+ * Resolve a `./tool-mode` export target to a path.
+ *
+ * An export value is either a string or a conditions object, and both appear in
+ * real packages. The entry is read from the declaration rather than guessed from
+ * a convention, so a package that points its entry elsewhere still loads.
+ * @param value - the export value.
+ * @returns the relative target, or undefined when there is none.
+ */
+function exportTarget(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'object' && value !== null) {
+        const conditions = value;
+        // `default` is the condition Node itself falls back to.
+        const target = conditions.default ?? conditions.import ?? conditions.node;
+        if (typeof target === 'string')
+            return target;
+    }
+    return undefined;
+}
+/**
+ * Read one bounded JSON file inside a package.
+ *
+ * @param path - absolute path to read.
+ * @param maxBytes - the size bound.
+ * @param what - a label for error messages.
+ * @returns the decoded value.
+ * @throws ManagementError when the file is missing, oversized, or not JSON.
+ */
+function readBoundedJson(path, maxBytes, what) {
+    let size;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        throw new ManagementError('INVALID_EXTENSION', 'discover', `the package does not ship ${what}`, `Add ${what} to the published package.`);
+    }
+    if (size > maxBytes) {
+        throw new ManagementError('INVALID_EXTENSION', 'discover', `${what} is ${size} bytes, over the ${maxBytes}-byte limit`, `Reduce ${what}; discovery reads it as bounded data before importing any code.`);
+    }
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        throw new ManagementError('INVALID_EXTENSION', 'discover', `${what} could not be read`, 'Check that the file is present and readable by the installing account.');
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new ManagementError('INVALID_EXTENSION', 'discover', `${what} is not valid JSON`, `Correct the JSON syntax in ${what}.`);
+    }
+}
+/**
+ * Discover an extension package without importing it.
+ *
+ * Enforces the EXT-13 package requirements: a `package.json` declaring `name`,
+ * `version`, `type: "module"`, an explicit `exports` map, and a `toolMode.manifest`
+ * field pointing at a manifest inside the package.
+ * @param packageDir - absolute path of the unpacked package.
+ * @returns the discovery result.
+ * @throws ManagementError with `INVALID_EXTENSION` for any violated requirement.
+ */
+export function discoverExtension(packageDir) {
+    const root = resolve(packageDir);
+    const manifest = readBoundedJson(join(root, 'package.json'), MAX_PACKAGE_JSON_BYTES, 'package.json');
+    if (typeof manifest !== 'object' || manifest === null || Array.isArray(manifest)) {
+        throw new ManagementError('INVALID_EXTENSION', 'discover', 'package.json is not an object', 'Ship a valid package.json.');
+    }
+    const pkg = manifest;
+    const packageName = pkg.name;
+    const packageVersion = pkg.version;
+    if (typeof packageName !== 'string' || packageName.length === 0) {
+        throw new ManagementError('INVALID_EXTENSION', 'discover', 'package.json declares no name', 'Declare a name.');
+    }
+    if (typeof packageVersion !== 'string' || packageVersion.length === 0) {
+        throw new ManagementError('INVALID_EXTENSION', 'discover', 'package.json declares no version', 'Declare a semantic version.');
+    }
+    if (pkg.type !== 'module') {
+        // ESM-only keeps the loading path single and avoids a CJS interop surface the
+        // host would otherwise have to reason about before importing anything.
+        throw new ManagementError('INVALID_EXTENSION', 'discover', 'package.json must declare "type": "module"', 'Publish the extension as an ES module.');
+    }
+    /**
+     * The `exports` map is required of a MODULE package and NOT of a declarative one.
+     *
+     * This check used to run here, unconditionally, and it made a declarative package
+     * UNDISCOVERABLE: such a package ships no code, so it has no entry points to export, and
+     * demanding an `exports` map asked it to declare something it does not have. The failure
+     * read "package.json must declare an explicit \"exports\" map" — advice a package with no
+     * module cannot act on.
+     *
+     * The requirement is now applied AFTER the manifest is read, where the execution kind is
+     * known. `exportsField` is still read here so the shape check happens in one place.
+     */
+    const exportsField = pkg.exports;
+    const toolMode = pkg.toolMode;
+    if (typeof toolMode !== 'object' || toolMode === null || typeof toolMode.manifest !== 'string') {
+        throw new ManagementError('INVALID_EXTENSION', 'discover', 'package.json must declare "toolMode": { "manifest": "./…" }', 'Add the toolMode discovery field naming the extension manifest.');
+    }
+    const declared = toolMode.manifest;
+    const manifestPath = resolve(root, declared);
+    if (!manifestPath.startsWith(root + sep)) {
+        throw new ManagementError('INVALID_EXTENSION', 'discover', 'the declared manifest path escapes the package directory', 'Reference the manifest by a package-relative path.');
+    }
+    const raw = readBoundedJson(manifestPath, MAX_MANIFEST_BYTES, 'the extension manifest');
+    /** A declarative package has no exports map at all, so there is no entry to look for. */
+    const entry = typeof exportsField === 'object' && exportsField !== null
+        ? exportTarget(exportsField['./tool-mode'])
+        : undefined;
+    const entryPath = entry === undefined ? undefined : resolve(root, entry);
+    if (entryPath !== undefined && !entryPath.startsWith(root + sep)) {
+        throw new ManagementError('INVALID_EXTENSION', 'discover', 'the ./tool-mode export points outside the package directory', 'Point the export at a file inside the package.');
+    }
+    // Named alidated because manifest already holds the parsed package.json above.
+    const validated = validateManifest(raw, { packageName, packageVersion, packageDir: root });
+    // The declared asset locks' qualification records are validated too (MODEL-05):
+    // a record that claims a qualified path must actually carry every field.
+    validateLockQualifications(validated, root);
+    /**
+     * The `exports` requirement, applied where the execution KIND is known.
+     *
+     * A module package must declare its public entry points, because the host resolves one in
+     * order to load it, and implicit resolution is not admitted. A DECLARATIVE package has no
+     * module to load: its behaviour is a set of recipe files resolved by the
+     * `recipes/<implementation-id>.json` convention instead. Requiring an `exports` map of it
+     * demanded a declaration it cannot meaningfully make, and rejected every declarative
+     * package before its kind could even be read.
+     */
+    const declarative = validated.execution.kind === 'declarative';
+    if (!declarative
+        && (typeof exportsField !== 'object' || exportsField === null || Object.keys(exportsField).length === 0)) {
+        throw new ManagementError('INVALID_EXTENSION', 'discover', 'package.json must declare an explicit "exports" map', 'Declare the public entry points; implicit resolution is not admitted.');
+    }
+    /**
+     * Licence resolution happens HERE rather than being left to each consumer.
+     *
+     * Every caller then resolves the same way, and a package that declares nothing gets
+     * the same explicit gap report as one that declares an incomplete set — rather than
+     * one consumer treating silence as permission and another not.
+     */
+    const { record: licenses, gaps: licenseGaps } = resolveLicenses(packageName, (validated.licenses ?? []).map((entry) => ({
+        layer: entry.layer,
+        name: entry.name,
+        url: entry.url,
+        openSource: entry.openSource,
+        redistribution: entry.redistribution,
+        attributionRequired: entry.attributionRequired,
+        ...entry.attributionText === undefined ? {} : { attributionText: entry.attributionText },
+        obligations: entry.obligations ?? [],
+    })));
+    /**
+     * Network behaviour is TAKEN FROM THE DECLARATION, and a package that declares
+     * nothing is treated as telemetry-bearing rather than telemetry-free: silence about
+     * telemetry cannot be read as an absence of telemetry (LIC-04).
+     */
+    const declaredNetwork = validated.network ?? { requiredTelemetry: true, otherNetworkUse: true };
+    const networkBehaviour = {
+        extensionId: packageName,
+        requiredTelemetry: declaredNetwork.requiredTelemetry,
+        otherNetworkUse: declaredNetwork.otherNetworkUse,
+        ...declaredNetwork.telemetryContent === undefined ? {} : { telemetryContent: declaredNetwork.telemetryContent },
+    };
+    return {
+        packageName,
+        packageVersion,
+        packageDir: root,
+        manifestPath,
+        ...entryPath === undefined ? {} : { entryPath },
+        manifest: validated,
+        exports: typeof exportsField === 'object' && exportsField !== null ? Object.keys(exportsField) : [],
+        licenses,
+        licenseGaps,
+        noNetwork: noNetworkEligibility(networkBehaviour),
+        networkDescription: describeNetwork(networkBehaviour),
+    };
+}
+//# sourceMappingURL=discovery.js.map

package/node_modules/@try-works/tool-mode-extension-sdk/lib/errors.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The machine-readable management error vocabulary (EXT-34).
+ *
+ * Every management failure carries a stable code, the operation that failed, and
+ * safe recovery advice. Recovery text is authored to be safe to show: it never
+ * contains a credential, a token, or an absolute path from the operator's disk,
+ * because these errors surface in logs and operator UIs.
+ *
+ * @module @try-works/tool-mode-extension-sdk/errors
+ */
+/** Every management error code the protocol defines (EXT-34). */
+export declare const MANAGEMENT_ERROR_CODES: readonly ["INVALID_EXTENSION", "INCOMPATIBLE_PROTOCOL", "UNSUPPORTED_PLATFORM", "INTEGRITY_MISMATCH", "PERMISSION_REQUIRED", "DEPENDENCY_UNSATISFIED", "TOOL_NAME_CONFLICT", "CONTRACT_MISMATCH", "EXTENSION_INACTIVE", "EXTENSION_IN_USE", "BUILTIN_PROTECTED", "EXTENSION_REVOKED", "EXTENSION_FAULT", "UPGRADE_FAILED", "CLEANUP_PENDING"];
+/** One management error code. */
+export type ManagementErrorCode = (typeof MANAGEMENT_ERROR_CODES)[number];
+/** The management operations an error can be attributed to. */
+export type ManagementOperation = 'discover' | 'install' | 'activate' | 'deactivate' | 'update' | 'uninstall' | 'prepare' | 'invoke';
+/** A structured management failure. */
+export interface ManagementErrorShape {
+    /** Stable machine-readable code. */
+    readonly code: ManagementErrorCode;
+    /** The operation that failed. */
+    readonly operation: ManagementOperation;
+    /** Human-readable description, safe to log. */
+    readonly message: string;
+    /** Safe recovery advice. Never contains credentials or operator paths. */
+    readonly recovery: string;
+    /** Whether retrying the same operation could succeed. */
+    readonly retryable: boolean;
+}
+/**
+ * A management failure raised by discovery, installation or lifecycle code.
+ *
+ * `retryable` is derived from the code rather than passed in, so a caller cannot
+ * accidentally mark a permission refusal as a transient fault the agent should
+ * retry in a loop.
+ */
+export declare class ManagementError extends Error {
+    readonly name = "ManagementError";
+    readonly code: ManagementErrorCode;
+    readonly operation: ManagementOperation;
+    readonly recovery: string;
+    readonly retryable: boolean;
+    constructor(code: ManagementErrorCode, operation: ManagementOperation, message: string, recovery: string);
+    /** Render the structured shape, for receipts and management surfaces. */
+    toShape(): ManagementErrorShape;
+}
+/**
+ * Strip anything credential-shaped from recovery advice.
+ *
+ * EXT-34 requires that recovery text never carries raw credentials. Advice is
+ * authored rather than interpolated, so this is a guard against a future edit
+ * that interpolates a path or a value by accident.
+ * @param text - the authored advice.
+ * @returns the advice with path- and credential-shaped spans removed.
+ */
+export declare function sanitizeRecovery(text: string): string;
+//# sourceMappingURL=errors.d.ts.map

package/node_modules/@try-works/tool-mode-extension-sdk/lib/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,iEAAiE;AACjE,eAAO,MAAM,sBAAsB,+UAgBzB,CAAA;AAEV,iCAAiC;AACjC,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEzE,+DAA+D;AAC/D,MAAM,MAAM,mBAAmB,GAC3B,UAAU,GACV,SAAS,GACT,UAAU,GACV,YAAY,GACZ,QAAQ,GACR,WAAW,GACX,SAAS,GACT,QAAQ,CAAA;AAQZ,uCAAuC;AACvC,MAAM,WAAW,oBAAoB;IACnC,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAA;IAClC,iCAAiC;IACjC,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAA;IACvC,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAkB,IAAI,qBAAoB;IAC1C,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAA;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;gBAGzB,IAAI,EAAE,mBAAmB,EACzB,SAAS,EAAE,mBAAmB,EAC9B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM;IASlB,yEAAyE;IACzE,OAAO,IAAI,oBAAoB;CAShC;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQrD"}

package/node_modules/@try-works/tool-mode-extension-sdk/lib/errors.js

@@ -0,0 +1,83 @@
+/**
+ * The machine-readable management error vocabulary (EXT-34).
+ *
+ * Every management failure carries a stable code, the operation that failed, and
+ * safe recovery advice. Recovery text is authored to be safe to show: it never
+ * contains a credential, a token, or an absolute path from the operator's disk,
+ * because these errors surface in logs and operator UIs.
+ *
+ * @module @try-works/tool-mode-extension-sdk/errors
+ */
+/** Every management error code the protocol defines (EXT-34). */
+export const MANAGEMENT_ERROR_CODES = [
+    'INVALID_EXTENSION',
+    'INCOMPATIBLE_PROTOCOL',
+    'UNSUPPORTED_PLATFORM',
+    'INTEGRITY_MISMATCH',
+    'PERMISSION_REQUIRED',
+    'DEPENDENCY_UNSATISFIED',
+    'TOOL_NAME_CONFLICT',
+    'CONTRACT_MISMATCH',
+    'EXTENSION_INACTIVE',
+    'EXTENSION_IN_USE',
+    'BUILTIN_PROTECTED',
+    'EXTENSION_REVOKED',
+    'EXTENSION_FAULT',
+    'UPGRADE_FAILED',
+    'CLEANUP_PENDING',
+];
+/** Whether a code's condition is worth retrying unchanged. */
+const RETRYABLE = new Set([
+    'EXTENSION_FAULT',
+    'CLEANUP_PENDING',
+]);
+/**
+ * A management failure raised by discovery, installation or lifecycle code.
+ *
+ * `retryable` is derived from the code rather than passed in, so a caller cannot
+ * accidentally mark a permission refusal as a transient fault the agent should
+ * retry in a loop.
+ */
+export class ManagementError extends Error {
+    name = 'ManagementError';
+    code;
+    operation;
+    recovery;
+    retryable;
+    constructor(code, operation, message, recovery) {
+        super(message);
+        this.code = code;
+        this.operation = operation;
+        this.recovery = recovery;
+        this.retryable = RETRYABLE.has(code);
+    }
+    /** Render the structured shape, for receipts and management surfaces. */
+    toShape() {
+        return {
+            code: this.code,
+            operation: this.operation,
+            message: this.message,
+            recovery: this.recovery,
+            retryable: this.retryable,
+        };
+    }
+}
+/**
+ * Strip anything credential-shaped from recovery advice.
+ *
+ * EXT-34 requires that recovery text never carries raw credentials. Advice is
+ * authored rather than interpolated, so this is a guard against a future edit
+ * that interpolates a path or a value by accident.
+ * @param text - the authored advice.
+ * @returns the advice with path- and credential-shaped spans removed.
+ */
+export function sanitizeRecovery(text) {
+    return text
+        // Windows and POSIX absolute paths.
+        .replace(/[A-Za-z]:\\[^\s"']*/g, '<path>')
+        .replace(/(?<![\w.])\/(?:[\w.-]+\/)+[\w.-]+/g, '<path>')
+        // Token-shaped spans.
+        .replace(/\b(?:npm_|ghp_|gho_|sk-)[A-Za-z0-9_-]{8,}/g, '<redacted>')
+        .replace(/\b[A-Fa-f0-9]{32,}\b/g, '<redacted>');
+}
+//# sourceMappingURL=errors.js.map