@nodetool-ai/agents 0.7.0-rc.23 → 0.8.2

package/dist/capabilities/settings.js

@@ -0,0 +1,226 @@
+/**
+ * The `settings` capability module — NodeTool's own configuration, reachable
+ * from sandboxed code as `@nodetool-ai/sandbox-nodetool/settings`.
+ *
+ * The catalog it reads is `@nodetool-ai/config`'s `settingCatalog()`, the same
+ * table the tRPC settings router answers `settings.list` from. That shared
+ * table is what makes the secret/non-secret split trustworthy here: a
+ * capability that decided whether `OPENAI_API_KEY` holds a credential by
+ * looking at the name would eventually be wrong, and being wrong once means a
+ * key in a model's context.
+ *
+ * ## Secrets are asked for, never set
+ *
+ * `set_setting` refuses a secret and there is no `set_secret`. The only path
+ * from guest code to a stored credential is {@link requestSecret}, which takes
+ * a *name and a reason* and no value: it opens a dialog in the user's client,
+ * they type the key there, and the client saves it over its own authenticated
+ * tRPC call. The value never enters the guest, the model's context, the chat
+ * transcript, or this process.
+ *
+ * The dialog is a host capability, not a fallback. A run that carries no
+ * `CapabilityRun.secretPrompt` — every headless run: a workflow on the
+ * kernel, the CLI, an eval — is refused by name rather than quietly writing
+ * something the user never saw.
+ *
+ * Reading a secret is unchanged and lives elsewhere: `nodetool.secrets.get`,
+ * bound by the run's declared `secretScope` at the sandbox bridge.
+ */
+import { settingCatalog, settingDefinition } from "@nodetool-ai/config";
+import { userIdOf } from "../tools/mcp-tool-support.js";
+import { getSettingSpec, listSecretsSpec, listSettingsSpec, requestSecretSpec, setSettingSpec } from "./settings.specs.js";
+import { isNonEmptyString, isString } from "../utils/type-guards.js";
+function refuse(kind, message) {
+    return { ok: false, error: message, error_kind: kind };
+}
+/**
+ * A name the catalog does not declare. The near-misses matter more than the
+ * refusal: a model that misspelled a key can fix the call from the answer.
+ */
+function unknownSetting(key) {
+    const near = settingCatalog()
+        .filter((def) => def.envVar.includes(key.toUpperCase()) ||
+        key.toUpperCase().includes(def.envVar))
+        .map((def) => def.envVar)
+        .slice(0, 10);
+    return refuse("unknown_setting", `NodeTool declares no setting named "${key}".` +
+        (near.length === 0
+            ? " Call list_settings to see what it does declare."
+            : ` Did you mean: ${near.join(", ")}?`));
+}
+/**
+ * Resolve one setting the way the server does: this user's saved value, then
+ * the process environment, then unset. The `Setting` model is imported lazily
+ * so the eager spec table never pulls the database in.
+ */
+async function resolveValue(context, envVar) {
+    const { Setting } = await import("@nodetool-ai/models");
+    const saved = await Setting.find(userIdOf(context), envVar);
+    if (saved && saved.value.length > 0) {
+        return { value: saved.value, source: "user" };
+    }
+    const fromEnv = process.env[envVar];
+    if (fromEnv !== undefined && fromEnv.length > 0) {
+        return { value: fromEnv, source: "env" };
+    }
+    return { value: null, source: "unset" };
+}
+async function viewOf(context, def) {
+    const { value, source } = await resolveValue(context, def.envVar);
+    return {
+        key: def.envVar,
+        group: def.group,
+        description: def.description,
+        allowed_values: def.enum ?? null,
+        value,
+        source
+    };
+}
+const listSettings = {
+    spec: listSettingsSpec,
+    impl: async (run, params) => {
+        const group = params["group"];
+        const wanted = settingCatalog().filter((def) => def.isSecret !== true &&
+            (!isNonEmptyString(group) ||
+                def.group.toLowerCase() === group.toLowerCase()));
+        const settings = await Promise.all(wanted.map((def) => viewOf(run.context, def)));
+        return { settings, groups: [...new Set(settings.map((s) => s.group))] };
+    }
+};
+const getSetting = {
+    spec: getSettingSpec,
+    impl: async (run, params) => {
+        const key = params["key"];
+        if (!isNonEmptyString(key)) {
+            return refuse("unknown_setting", "Pass the setting's name as `key`.");
+        }
+        const def = settingDefinition(key);
+        if (def === undefined)
+            return unknownSetting(key);
+        if (def.isSecret === true) {
+            return refuse("is_secret", `${key} holds a credential, so its value is not readable here. Read it with ` +
+                "nodetool.secrets.get, which works only if this run declares the name in its secret scope.");
+        }
+        return viewOf(run.context, def);
+    }
+};
+const setSetting = {
+    spec: setSettingSpec,
+    impl: async (run, params) => {
+        const key = params["key"];
+        const value = params["value"];
+        if (!isNonEmptyString(key)) {
+            return refuse("unknown_setting", "Pass the setting's name as `key`.");
+        }
+        if (!isString(value)) {
+            return refuse("invalid_value", "Pass the new value as a string in `value`.");
+        }
+        const def = settingDefinition(key);
+        if (def === undefined)
+            return unknownSetting(key);
+        if (def.isSecret === true) {
+            return refuse("is_secret", `${key} holds a credential and cannot be set from code. Call request_secret to ask ` +
+                "the user to enter it themselves.");
+        }
+        if (def.enum !== undefined && !def.enum.includes(value)) {
+            return refuse("invalid_value", `${key} accepts only: ${def.enum.join(", ")}.`);
+        }
+        const { Setting } = await import("@nodetool-ai/models");
+        await Setting.upsert({ userId: userIdOf(run.context), key, value });
+        return { ok: true, key, value };
+    }
+};
+const listSecrets = {
+    spec: listSecretsSpec,
+    impl: async (run) => {
+        const declared = settingCatalog().filter((def) => def.isSecret === true);
+        const { Secret } = await import("@nodetool-ai/models");
+        const [stored] = await Secret.listForUser(userIdOf(run.context), 1000);
+        const storedKeys = new Set(stored.map((row) => row.key));
+        const secrets = declared.map((def) => ({
+            key: def.envVar,
+            group: def.group,
+            description: def.description,
+            configured: storedKeys.has(def.envVar) || Boolean(process.env[def.envVar])
+        }));
+        // A credential stored under a name NodeTool does not ship — a user's own,
+        // or one a previous request_secret created. It is configured by
+        // definition, and hiding it would have code ask for what already exists.
+        for (const key of storedKeys) {
+            if (!declared.some((def) => def.envVar === key)) {
+                secrets.push({
+                    key,
+                    group: "Custom",
+                    description: "",
+                    configured: true
+                });
+            }
+        }
+        return { secrets };
+    }
+};
+/**
+ * Ask the user for a credential.
+ *
+ * Everything this returns is a fact about the store, never about the value:
+ * `saved` means one now exists under that name.
+ */
+const requestSecret = {
+    spec: requestSecretSpec,
+    impl: async (run, params) => {
+        const key = params["key"];
+        if (!isNonEmptyString(key)) {
+            return refuse("unknown_setting", "Pass the secret's name as `key`.");
+        }
+        const prompt = run.secretPrompt;
+        if (prompt === undefined) {
+            return refuse("no_dialog", "This run has no interactive client, so there is nowhere to show the entry dialog. " +
+                `A secret is only ever set by the user: ask them to add ${key} under Settings > API Keys.`);
+        }
+        const declared = settingDefinition(key);
+        const request = { key };
+        if (declared?.description !== undefined) {
+            Object.assign(request, { description: declared.description });
+        }
+        if (isNonEmptyString(params["reason"])) {
+            Object.assign(request, { reason: params["reason"] });
+        }
+        if (isNonEmptyString(params["help_url"])) {
+            Object.assign(request, { helpUrl: params["help_url"] });
+        }
+        // The user's wait is not the guest program's. Charged to a code action's
+        // wall clock, the time spent finding an API key kills the very program
+        // that asked for it — the same reason the permission gate suspends.
+        const resume = run.gate.clock?.suspend();
+        let status;
+        try {
+            status = await prompt(request);
+        }
+        finally {
+            resume?.();
+        }
+        if (status !== "saved") {
+            return refuse("declined", `The user did not enter ${key}. Do not ask again in this run — continue without it, ` +
+                "or tell them what cannot be done.");
+        }
+        return {
+            ok: true,
+            key,
+            configured: true,
+            note: "The value was saved directly by the user and is not readable here. Read it with " +
+                "nodetool.secrets.get if this run declares the name in its secret scope."
+        };
+    }
+};
+export const SETTINGS_CAPABILITIES = [
+    listSettings,
+    getSetting,
+    setSetting,
+    listSecrets,
+    requestSecret
+];
+export const module = {
+    module: "settings",
+    exports: SETTINGS_CAPABILITIES
+};
+//# sourceMappingURL=settings.js.map

package/dist/capabilities/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../../src/capabilities/settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EACL,cAAc,EACd,iBAAiB,EAElB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAMxD,OAAO,EACL,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AA4BrE,SAAS,MAAM,CAAC,IAAe,EAAE,OAAe;IAC9C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;AACzD,CAAC;AAED;;;GAGG;AACH,SAAS,cAAc,CAAC,GAAW;IACjC,MAAM,IAAI,GAAG,cAAc,EAAE;SAC1B,MAAM,CACL,CAAC,GAAG,EAAE,EAAE,CACN,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;QACtC,GAAG,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CACzC;SACA,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC;SACxB,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChB,OAAO,MAAM,CACX,iBAAiB,EACjB,uCAAuC,GAAG,IAAI;QAC5C,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;YAChB,CAAC,CAAC,kDAAkD;YACpD,CAAC,CAAC,kBAAkB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAC5C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,YAAY,CACzB,OAA0B,EAC1B,MAAc;IAEd,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;IAC5D,IAAI,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAChD,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACpC,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC3C,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC1C,CAAC;AAED,KAAK,UAAU,MAAM,CACnB,OAA0B,EAC1B,GAAwB;IAExB,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAClE,OAAO;QACL,GAAG,EAAE,GAAG,CAAC,MAAM;QACf,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,cAAc,EAAE,GAAG,CAAC,IAAI,IAAI,IAAI;QAChC,KAAK;QACL,MAAM;KACP,CAAC;AACJ,CAAC;AAED,MAAM,YAAY,GAAqB;IACrC,IAAI,EAAE,gBAAgB;IACtB,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE;QAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;QAC9B,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC,MAAM,CACpC,CAAC,GAAG,EAAE,EAAE,CACN,GAAG,CAAC,QAAQ,KAAK,IAAI;YACrB,CAAC,CAAC,gBAAgB,CAAC,KAAK,CAAC;gBACvB,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,WAAW,EAAE,CAAC,CACrD,CAAC;QACF,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAChC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAC9C,CAAC;QACF,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1E,CAAC;CACF,CAAC;AAEF,MAAM,UAAU,GAAqB;IACnC,IAAI,EAAE,cAAc;IACpB,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE;QAC1B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,OAAO,MAAM,CAAC,iBAAiB,EAAE,mCAAmC,CAAC,CAAC;QACxE,CAAC;QACD,MAAM,GAAG,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,cAAc,CAAC,GAAG,CAAC,CAAC;QAClD,IAAI,GAAG,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC1B,OAAO,MAAM,CACX,WAAW,EACX,GAAG,GAAG,uEAAuE;gBAC3E,2FAA2F,CAC9F,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAClC,CAAC;CACF,CAAC;AAEF,MAAM,UAAU,GAAqB;IACnC,IAAI,EAAE,cAAc;IACpB,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE;QAC1B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;QAC9B,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,OAAO,MAAM,CAAC,iBAAiB,EAAE,mCAAmC,CAAC,CAAC;QACxE,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACrB,OAAO,MAAM,CAAC,eAAe,EAAE,4CAA4C,CAAC,CAAC;QAC/E,CAAC;QACD,MAAM,GAAG,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,cAAc,CAAC,GAAG,CAAC,CAAC;QAClD,IAAI,GAAG,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC1B,OAAO,MAAM,CACX,WAAW,EACX,GAAG,GAAG,8EAA8E;gBAClF,kCAAkC,CACrC,CAAC;QACJ,CAAC;QACD,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACxD,OAAO,MAAM,CACX,eAAe,EACf,GAAG,GAAG,kBAAkB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC/C,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC;QACxD,MAAM,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;QACpE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;IAClC,CAAC;CACF,CAAC;AAEF,MAAM,WAAW,GAAqB;IACpC,IAAI,EAAE,eAAe;IACrB,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QAClB,MAAM,QAAQ,GAAG,cAAc,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC;QACzE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC;QACvD,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC;QACvE,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QACzD,MAAM,OAAO,GAAiB,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACnD,GAAG,EAAE,GAAG,CAAC,MAAM;YACf,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,UAAU,EACR,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;SACjE,CAAC,CAAC,CAAC;QACJ,0EAA0E;QAC1E,gEAAgE;QAChE,yEAAyE;QACzE,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,EAAE,CAAC;gBAChD,OAAO,CAAC,IAAI,CAAC;oBACX,GAAG;oBACH,KAAK,EAAE,QAAQ;oBACf,WAAW,EAAE,EAAE;oBACf,UAAU,EAAE,IAAI;iBACjB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,CAAC;IACrB,CAAC;CACF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,aAAa,GAAqB;IACtC,IAAI,EAAE,iBAAiB;IACvB,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE;QAC1B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,OAAO,MAAM,CAAC,iBAAiB,EAAE,kCAAkC,CAAC,CAAC;QACvE,CAAC;QACD,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,CAAC;QAChC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,MAAM,CACX,WAAW,EACX,oFAAoF;gBAClF,0DAA0D,GAAG,6BAA6B,CAC7F,CAAC;QACJ,CAAC;QACD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACxC,MAAM,OAAO,GAAwB,EAAE,GAAG,EAAE,CAAC;QAC7C,IAAI,QAAQ,EAAE,WAAW,KAAK,SAAS,EAAE,CAAC;YACxC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,WAAW,EAAE,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;QAChE,CAAC;QACD,IAAI,gBAAgB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;YACvC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QACvD,CAAC;QACD,IAAI,gBAAgB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;YACzC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAC1D,CAAC;QAED,yEAAyE;QACzE,uEAAuE;QACvE,oEAAoE;QACpE,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC;QACzC,IAAI,MAA4B,CAAC;QACjC,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;QACjC,CAAC;gBAAS,CAAC;YACT,MAAM,EAAE,EAAE,CAAC;QACb,CAAC;QAED,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACvB,OAAO,MAAM,CACX,UAAU,EACV,0BAA0B,GAAG,wDAAwD;gBACnF,mCAAmC,CACtC,CAAC;QACJ,CAAC;QACD,OAAO;YACL,EAAE,EAAE,IAAI;YACR,GAAG;YACH,UAAU,EAAE,IAAI;YAChB,IAAI,EACF,kFAAkF;gBAClF,yEAAyE;SAC5E,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAgC;IAChE,YAAY;IACZ,UAAU;IACV,UAAU;IACV,WAAW;IACX,aAAa;CACd,CAAC;AAEF,MAAM,CAAC,MAAM,MAAM,GAAqB;IACtC,MAAM,EAAE,UAAU;IAClB,OAAO,EAAE,qBAAqB;CAC/B,CAAC"}

package/dist/capabilities/settings.specs.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The `settings` module's specs — data only, no implementation.
+ *
+ * Split out for the reason every `.specs.ts` is: the registry's eager spec
+ * table imports this file synchronously, so nothing the implementation pulls
+ * in (`@nodetool-ai/models`, the database) reaches the entry graph.
+ *
+ * Five wire names, and the shape of the set is the design. Four of them read
+ * or write ordinary configuration. The fifth, `request_secret`, is the only
+ * way sandboxed code can cause a credential to be stored — and it takes no
+ * value. There is deliberately no `set_secret`.
+ */
+import { z } from "zod";
+import type { CapabilitySpec } from "./types.js";
+export declare const LIST_SETTINGS_TOOL_NAME = "list_settings";
+export declare const GET_SETTING_TOOL_NAME = "get_setting";
+export declare const SET_SETTING_TOOL_NAME = "set_setting";
+export declare const LIST_SECRETS_TOOL_NAME = "list_secrets";
+export declare const REQUEST_SECRET_TOOL_NAME = "request_secret";
+export declare const listSettingsSchema: z.ZodObject<{
+    group: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const getSettingSchema: z.ZodObject<{
+    key: z.ZodString;
+}, z.core.$strip>;
+export declare const setSettingSchema: z.ZodObject<{
+    key: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strip>;
+export declare const listSecretsSchema: z.ZodObject<{}, z.core.$strip>;
+export declare const requestSecretSchema: z.ZodObject<{
+    key: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+    help_url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const listSettingsSpec: CapabilitySpec;
+export declare const getSettingSpec: CapabilitySpec;
+export declare const setSettingSpec: CapabilitySpec;
+export declare const listSecretsSpec: CapabilitySpec;
+export declare const requestSecretSpec: CapabilitySpec;
+export declare const settingsSpecs: readonly CapabilitySpec[];
+//# sourceMappingURL=settings.specs.d.ts.map

package/dist/capabilities/settings.specs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.specs.d.ts","sourceRoot":"","sources":["../../src/capabilities/settings.specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,eAAO,MAAM,uBAAuB,kBAAkB,CAAC;AACvD,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AACnD,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AACnD,eAAO,MAAM,sBAAsB,iBAAiB,CAAC;AACrD,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AAEzD,eAAO,MAAM,kBAAkB;;iBAO7B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;iBAM3B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;iBAS3B,CAAC;AAEH,eAAO,MAAM,iBAAiB,gCAAe,CAAC;AAE9C,eAAO,MAAM,mBAAmB;;;;iBAkB9B,CAAC;AAEH,eAAO,MAAM,gBAAgB,EAAE,cAc9B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,cAa5B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,cAa5B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,cAS7B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,cAgB/B,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,SAAS,cAAc,EAMlD,CAAC"}

package/dist/capabilities/settings.specs.js

@@ -0,0 +1,126 @@
+/**
+ * The `settings` module's specs — data only, no implementation.
+ *
+ * Split out for the reason every `.specs.ts` is: the registry's eager spec
+ * table imports this file synchronously, so nothing the implementation pulls
+ * in (`@nodetool-ai/models`, the database) reaches the entry graph.
+ *
+ * Five wire names, and the shape of the set is the design. Four of them read
+ * or write ordinary configuration. The fifth, `request_secret`, is the only
+ * way sandboxed code can cause a credential to be stored — and it takes no
+ * value. There is deliberately no `set_secret`.
+ */
+import { z } from "zod";
+import { zodToJsonSchema } from "@nodetool-ai/runtime";
+import { isNonEmptyString } from "../utils/type-guards.js";
+export const LIST_SETTINGS_TOOL_NAME = "list_settings";
+export const GET_SETTING_TOOL_NAME = "get_setting";
+export const SET_SETTING_TOOL_NAME = "set_setting";
+export const LIST_SECRETS_TOOL_NAME = "list_secrets";
+export const REQUEST_SECRET_TOOL_NAME = "request_secret";
+export const listSettingsSchema = z.object({
+    group: z
+        .string()
+        .optional()
+        .describe('Omit to list every setting. Pass one group name to list only that group, e.g. "Folders".')
+});
+export const getSettingSchema = z.object({
+    key: z
+        .string()
+        .describe('The setting\'s environment-variable name, e.g. "AUTOSAVE_INTERVAL_MINUTES".')
+});
+export const setSettingSchema = z.object({
+    key: z
+        .string()
+        .describe("The setting's environment-variable name."),
+    value: z
+        .string()
+        .describe("The new value, as a string. Must be one of the setting's allowed values when it declares an enum.")
+});
+export const listSecretsSchema = z.object({});
+export const requestSecretSchema = z.object({
+    key: z
+        .string()
+        .describe('The secret\'s name, e.g. "STRIPE_API_KEY". Use the name the service is registered under when there is one — read list_secrets first.'),
+    reason: z
+        .string()
+        .optional()
+        .describe("Why you need it, in one sentence. Shown to the user in the dialog, so write it for them."),
+    help_url: z
+        .string()
+        .optional()
+        .describe("Where the user obtains the key. Rendered as a link when it is an https URL.")
+});
+export const listSettingsSpec = {
+    name: LIST_SETTINGS_TOOL_NAME,
+    description: "List NodeTool's configuration settings with their group, description, allowed values, and current value. " +
+        "Secrets are listed by list_secrets instead, and never carry a value here.",
+    inputSchema: zodToJsonSchema(listSettingsSchema),
+    zodSchema: listSettingsSchema,
+    category: "read",
+    userMessage: (params) => {
+        const group = params["group"];
+        return isNonEmptyString(group)
+            ? `Reading ${group} settings`
+            : "Reading settings";
+    }
+};
+export const getSettingSpec = {
+    name: GET_SETTING_TOOL_NAME,
+    description: "Read one configuration setting's current value, resolved from this user's saved settings and then the " +
+        "process environment. Refuses a secret: read those with nodetool.secrets.get, which is bound by the " +
+        "secret scope this run declares.",
+    inputSchema: zodToJsonSchema(getSettingSchema),
+    zodSchema: getSettingSchema,
+    category: "read",
+    userMessage: (params) => {
+        const key = params["key"];
+        return isNonEmptyString(key) ? `Reading setting ${key}` : "Reading a setting";
+    }
+};
+export const setSettingSpec = {
+    name: SET_SETTING_TOOL_NAME,
+    description: "Change one configuration setting for this user. Only a setting NodeTool declares can be set, and a " +
+        "setting that declares allowed values accepts only those. Cannot set a secret — call request_secret, " +
+        "which asks the user to enter it themselves.",
+    inputSchema: zodToJsonSchema(setSettingSchema),
+    zodSchema: setSettingSchema,
+    category: "write",
+    userMessage: (params) => {
+        const key = params["key"];
+        return isNonEmptyString(key) ? `Changing setting ${key}` : "Changing a setting";
+    }
+};
+export const listSecretsSpec = {
+    name: LIST_SECRETS_TOOL_NAME,
+    description: "List the credentials NodeTool knows about and whether each one is configured on this install. " +
+        "Values are never returned. Use this to find out what is missing before asking for it.",
+    inputSchema: zodToJsonSchema(listSecretsSchema),
+    zodSchema: listSecretsSchema,
+    category: "read",
+    userMessage: () => "Checking which credentials are configured"
+};
+export const requestSecretSpec = {
+    name: REQUEST_SECRET_TOOL_NAME,
+    description: "Ask the user to enter a credential. This opens a dialog in their NodeTool client where they type the " +
+        "value; it is saved directly from there. You never send the value and never receive it — the answer is " +
+        "only whether they saved one. This is the only way to set a secret. Read it afterwards with " +
+        "nodetool.secrets.get, which works only if this run declares the name in its secret scope.",
+    inputSchema: zodToJsonSchema(requestSecretSchema),
+    zodSchema: requestSecretSchema,
+    category: "write",
+    userMessage: (params) => {
+        const key = params["key"];
+        return isNonEmptyString(key)
+            ? `Asking you to enter ${key}`
+            : "Asking you to enter a credential";
+    }
+};
+export const settingsSpecs = [
+    listSettingsSpec,
+    getSettingSpec,
+    setSettingSpec,
+    listSecretsSpec,
+    requestSecretSpec
+];
+//# sourceMappingURL=settings.specs.js.map

package/dist/capabilities/settings.specs.js.map

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

package/dist/capabilities/shared.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The `shared` capability module — run-scoped agent memory.
+ *
+ * Three capabilities that used to be three `Tool` subclasses in
+ * `../tools/shared-tools.ts`, which now assembles them from these specs.
+ * Wire names, descriptions, schemas and behaviour are unchanged.
+ *
+ * Separate from `memory` on purpose: that module is memory, which
+ * outlives the run and lives in the database. These read and write
+ * `run.context.memory` — the `AgentMemory` a run carries and discards. The
+ * naming says the lifetimes: `nodetool.shared` run-scoped beside
+ * `nodetool.memory` thread-scoped.
+ *
+ * Mount policy stays with the executors. `getSharedTools()` builds a belt from
+ * these specs, and every step executor pushes that belt onto its own toolset —
+ * the host never mounts these.
+ *
+ * Earlier versions auto-injected every memory entry into every step's user
+ * message. That was wasteful: a large upstream result bloated every downstream
+ * prompt even when the step needed one entry. The pattern here is progressive
+ * disclosure — `list_shared` returns metadata, `read_shared` returns the values
+ * the model asks for, and `share_result` publishes into the `shared:`
+ * namespace.
+ *
+ * Design: docs/tool-class-retirement-design.md § "The `shared` module".
+ */
+import type { CapabilityExport, CapabilityModule } from "./types.js";
+declare const listShared: CapabilityExport;
+declare const readShared: CapabilityExport;
+declare const shareResult: CapabilityExport;
+/** Every shared-memory capability, in the order shared-tools.ts declared them. */
+export declare const SHARED_CAPABILITIES: readonly CapabilityExport[];
+export declare const module: CapabilityModule;
+export { listShared, readShared, shareResult };
+//# sourceMappingURL=shared.d.ts.map

package/dist/capabilities/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/capabilities/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAqErE,QAAA,MAAM,UAAU,EAAE,gBA4BjB,CAAC;AAMF,QAAA,MAAM,UAAU,EAAE,gBA4BjB,CAAC;AAMF,QAAA,MAAM,WAAW,EAAE,gBAqBlB,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,EAAE,SAAS,gBAAgB,EAI1D,CAAC;AAEF,eAAO,MAAM,MAAM,EAAE,gBAGpB,CAAC;AAEF,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC"}

package/dist/capabilities/shared.js

@@ -0,0 +1,165 @@
+/**
+ * The `shared` capability module — run-scoped agent memory.
+ *
+ * Three capabilities that used to be three `Tool` subclasses in
+ * `../tools/shared-tools.ts`, which now assembles them from these specs.
+ * Wire names, descriptions, schemas and behaviour are unchanged.
+ *
+ * Separate from `memory` on purpose: that module is memory, which
+ * outlives the run and lives in the database. These read and write
+ * `run.context.memory` — the `AgentMemory` a run carries and discards. The
+ * naming says the lifetimes: `nodetool.shared` run-scoped beside
+ * `nodetool.memory` thread-scoped.
+ *
+ * Mount policy stays with the executors. `getSharedTools()` builds a belt from
+ * these specs, and every step executor pushes that belt onto its own toolset —
+ * the host never mounts these.
+ *
+ * Earlier versions auto-injected every memory entry into every step's user
+ * message. That was wasteful: a large upstream result bloated every downstream
+ * prompt even when the step needed one entry. The pattern here is progressive
+ * disclosure — `list_shared` returns metadata, `read_shared` returns the values
+ * the model asks for, and `share_result` publishes into the `shared:`
+ * namespace.
+ *
+ * Design: docs/tool-class-retirement-design.md § "The `shared` module".
+ */
+import { memoryKeys } from "@nodetool-ai/runtime";
+import { listSharedSpec, readSharedSpec, shareResultSpec } from "./shared.specs.js";
+import { isString } from "../utils/type-guards.js";
+/** Maximum bytes of `description` returned per entry from list_shared. */
+const MAX_DESCRIPTION_CHARS = 240;
+/** Hard upper bound on entries returned in a single list_shared call. */
+const MAX_LIST_ENTRIES = 200;
+/**
+ * Normalize the key argument of `share_result`, which takes the suffix after
+ * `shared:` while `read_shared` and `list_shared` deal in full keys. A model
+ * that hands a full key back to the write side minted `shared:shared:<key>` —
+ * observed in a live run. Stripping the prefix makes the write idempotent
+ * under a round trip through either read tool.
+ *
+ * The cost is that a literal key `shared:shared:x` can no longer be created.
+ * Nothing wants one, and the tool description says the prefix is optional.
+ */
+function sharedSuffix(key) {
+    return key.startsWith("shared:") ? key.slice("shared:".length) : key;
+}
+function describeEntry(entry) {
+    const serialized = isString(entry.value)
+        ? entry.value
+        : (() => {
+            try {
+                return JSON.stringify(entry.value);
+            }
+            catch {
+                return String(entry.value);
+            }
+        })();
+    return {
+        key: entry.key,
+        kind: entry.kind,
+        title: entry.title,
+        description: entry.description && entry.description.length > MAX_DESCRIPTION_CHARS
+            ? entry.description.slice(0, MAX_DESCRIPTION_CHARS) + "…"
+            : entry.description,
+        source: entry.source,
+        valueBytes: serialized.length,
+        createdAt: new Date(entry.createdAt).toISOString()
+    };
+}
+// ---------------------------------------------------------------------------
+// list_shared
+// ---------------------------------------------------------------------------
+const listShared = {
+    spec: listSharedSpec,
+    impl: async (run, params) => {
+        const kindFilter = Array.isArray(params.kind)
+            ? params.kind
+            : undefined;
+        const keyPrefix = isString(params.key_prefix)
+            ? params.key_prefix
+            : undefined;
+        const sources = Array.isArray(params.sources)
+            ? params.sources
+            : undefined;
+        const entries = run.context.memory.list({
+            kind: kindFilter,
+            keyPrefix,
+            sources
+        });
+        const truncated = entries.length > MAX_LIST_ENTRIES;
+        const sliced = truncated ? entries.slice(0, MAX_LIST_ENTRIES) : entries;
+        return {
+            total: entries.length,
+            returned: sliced.length,
+            truncated,
+            entries: sliced.map(describeEntry)
+        };
+    }
+};
+// ---------------------------------------------------------------------------
+// read_shared
+// ---------------------------------------------------------------------------
+const readShared = {
+    spec: readSharedSpec,
+    impl: async (run, params) => {
+        const keys = Array.isArray(params.keys)
+            ? params.keys.map(String)
+            : [];
+        const found = {};
+        const missing = [];
+        for (const key of keys) {
+            // A bare suffix is what `share_result` accepts, so a model that reads
+            // back what it just wrote often asks for one. Retry the miss under the
+            // `shared:` namespace before reporting it, and report under the key that
+            // was asked for either way.
+            const entry = run.context.memory.get(key) ??
+                (key.includes(":")
+                    ? undefined
+                    : run.context.memory.get(memoryKeys.shared(key)));
+            if (entry) {
+                found[key] = entry;
+            }
+            else {
+                missing.push(key);
+            }
+        }
+        return { entries: found, missing };
+    }
+};
+// ---------------------------------------------------------------------------
+// share_result
+// ---------------------------------------------------------------------------
+const shareResult = {
+    spec: shareResultSpec,
+    impl: async (run, params) => {
+        const suffix = sharedSuffix(String(params.key));
+        const fullKey = memoryKeys.shared(suffix);
+        const entry = run.context.memory.set({
+            key: fullKey,
+            kind: "shared",
+            value: params.value,
+            title: isString(params.title) ? params.title : suffix,
+            description: isString(params.description) ? params.description : undefined,
+            source: "share_result"
+        });
+        return {
+            ok: true,
+            key: entry.key,
+            kind: entry.kind,
+            createdAt: new Date(entry.createdAt).toISOString()
+        };
+    }
+};
+/** Every shared-memory capability, in the order shared-tools.ts declared them. */
+export const SHARED_CAPABILITIES = [
+    listShared,
+    readShared,
+    shareResult
+];
+export const module = {
+    module: "shared",
+    exports: SHARED_CAPABILITIES
+};
+export { listShared, readShared, shareResult };
+//# sourceMappingURL=shared.js.map

package/dist/capabilities/shared.js.map

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

package/dist/capabilities/shared.specs.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The `shared` module's specs — data only, no implementation.
+ *
+ * Split out so a belt can be assembled synchronously: the registry's eager
+ * spec table imports this file, never `shared.ts`, so nothing the
+ * implementations pull in reaches the entry graph. `shared.ts` imports these
+ * back and attaches each to its implementation, so there is one spec object
+ * behind both halves.
+ *
+ * Wire names, descriptions and schemas are the ones the three `Tool`
+ * subclasses in `../tools/shared-tools.ts` carried, unchanged.
+ */
+import type { CapabilitySpec } from "./types.js";
+export declare const listSharedSpec: CapabilitySpec;
+export declare const readSharedSpec: CapabilitySpec;
+export declare const shareResultSpec: CapabilitySpec;
+/** Every spec this module declares, in declaration order. */
+export declare const sharedSpecs: readonly CapabilitySpec[];
+//# sourceMappingURL=shared.specs.d.ts.map

package/dist/capabilities/shared.specs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.specs.d.ts","sourceRoot":"","sources":["../../src/capabilities/shared.specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,eAAO,MAAM,cAAc,EAAE,cA6C5B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,cA8B5B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,cA2C7B,CAAC;AAEF,6DAA6D;AAC7D,eAAO,MAAM,WAAW,EAAE,SAAS,cAAc,EAIhD,CAAC"}