@falkenslab/agent-kit 0.24.0 → 0.25.0

package/dist/index.js

@@ -17,7 +17,7 @@ export { knowledge } from "./extensions/knowledge/index.js";
 export { memory } from "./extensions/memory/index.js";
 export { describeCapability, readExtensionManifest, } from "./core/extensions.js";
 export { checkRequirements } from "./core/extensionRequirements.js";
-export { addExtension, codeStoreDir, installTarget, scopePrivateDir, extensionDataDir, extensionOptionStates, setExtensionOptions, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, } from "./core/externalExtensions.js";
+export { addExtension, codeStoreDir, installTarget, scopePrivateDir, extensionDataDir, extensionOptionStates, setExtensionOptions, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, isRemoteServer, remoteHosts, remoteServerName, } from "./core/externalExtensions.js";
 export { packageCacheDir } from "./core/npxPackages.js";
 export { addMarketplace, findPlugin, inspectMarketplace, installFromMarketplace, listMarketplaces, readMarketplaceManifest, removeMarketplace, resolvePluginSource, updateMarketplace, } from "./core/marketplaces.js";
 export { extensionCatalog, installExtension, restoreExtensions, updateExtension } from "./core/extensionCatalog.js";

package/dist/tui/extensionCommand.js

@@ -2,7 +2,7 @@ import { stat } from "node:fs/promises";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { addMarketplace, findPlugin, inspectMarketplace, installFromMarketplace, removeMarketplace, updateMarketplace, } from "../core/marketplaces.js";
-import { addExtension, extensionOptionStates, installTarget, folderSize, isGitSource, listInstalled, removeExtension, setExtensionEnabled, setExtensionOptions, } from "../core/externalExtensions.js";
+import { addExtension, extensionOptionStates, installTarget, folderSize, isGitSource, isRemoteServer, remoteHosts, listInstalled, removeExtension, setExtensionEnabled, setExtensionOptions, } from "../core/externalExtensions.js";
 import { describe, describeOptions } from "../chat/extensions.js";
 import { extensionCatalog, knownMarketplaces as catalogMarketplaces, restoreExtensions, updateExtension } from "../core/extensionCatalog.js";
 import { trustWorkspace } from "../core/workspaceTrust.js";
@@ -129,9 +129,12 @@ export async function runExtensionCommand(argv, options) {
                 // Installed into the workspace by the person: trusted there as it is.
                 const trusted = async (name) => void (scope === "project" && (await trustWorkspace(options.dirs, [name])));
                 // What it needs and this computer lacks (#63): said, never installed.
-                const lacking = (missing) => {
+                const lacking = (missing, remote = []) => {
                     for (const line of missing)
                         write(`It ${line}.`);
+                    // Where what the agent sends goes (#61).
+                    if (remote.length)
+                        write(`It talks to ${remote.join(", ")}: what the agent sends there leaves this computer.`);
                 };
                 // A plugin of a marketplace, unless it's a folder here or a git URL.
                 const isFolder = await stat(path.resolve(source)).then((found) => found.isDirectory(), () => false);
@@ -142,7 +145,7 @@ export async function runExtensionCommand(argv, options) {
                     await trusted(result.name);
                     await configure(result.name, dir);
                     write(`Linked ${result.name} in the ${scope} scope: it runs from ${path.resolve(source)}, whose files aren't checked. A rebuild takes effect when its server starts again (a new session, or \`/extensions disable\` and \`enable\` in the chat).`);
-                    lacking(result.missing);
+                    lacking(result.missing, result.remote);
                     return true;
                 }
                 if (!isFolder && !isGitSource(source) && /^[A-Za-z0-9][\w.-]*(@[A-Za-z0-9][\w.-]*)?$/.test(source)) {
@@ -158,7 +161,7 @@ export async function runExtensionCommand(argv, options) {
                     await trusted(result.name);
                     await configure(result.name, dir);
                     write(`${result.replaced ? "Reinstalled" : "Installed"} ${result.name} from ${result.marketplace} in the ${scope} scope (${dir})${result.commit ? `, at ${result.commit.slice(0, 12)}` : ""}. It's enabled: it runs from the next session.`);
-                    lacking(result.missing);
+                    lacking(result.missing, result.remote);
                     return true;
                 }
                 const subdir = value("path");
@@ -166,7 +169,7 @@ export async function runExtensionCommand(argv, options) {
                 await trusted(result.name);
                 await configure(result.name, dir);
                 write(`${result.replaced ? "Reinstalled" : "Installed"} ${result.name} in the ${scope} scope (${dir})${result.commit ? `, at ${result.commit.slice(0, 12)}` : ""}. It's enabled: it runs from the next session.`);
-                lacking(result.missing);
+                lacking(result.missing, result.remote);
                 return true;
             }
             case "remove":
@@ -434,7 +437,9 @@ async function info(extension) {
         ...field("Options", Object.entries(manifest.userConfig)
             .map(([key, option]) => `${key} (${[option.title, option.required && "required", option.sensitive && "secret"].filter(Boolean).join(", ")})`)
             .join(", ") || undefined),
-        ...field("Variables", Object.values(manifest.servers).flatMap((server) => Object.keys(server.env ?? {})).join(", ") || undefined),
+        ...field("Variables", Object.values(manifest.servers).flatMap((server) => (isRemoteServer(server) ? [] : Object.keys(server.env ?? {}))).join(", ") || undefined),
+        // Where what the agent sends goes (#61): a remote server's host.
+        ...field("Talks to", remoteHosts(manifest).join(", ") || undefined),
         ...field("Installed", `${extension.scope} scope, ${extension.lock.enabled ? "enabled" : "disabled"}, on ${extension.lock.installed}, from ${describe(extension).split("  from ")[1]}`),
         ...field("Data", (await stat(extension.dataDir).catch(() => null))?.isDirectory() ? `${extension.dataDir} (${formatSize(await folderSize(extension.dataDir))})` : undefined),
         ...field("README", (await stat(readme).catch(() => null))?.isFile() ? readme : undefined),

package/extensions/awareness/skills/extensions/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: extensions
+description: Helping the person with this agent's extensions - what each installed one lets you do, setting its options, why one is off, what the catalogs offer for a task, signing in to a remote one, installing, updating and removing, adding a catalog. Load it whenever the person asks about extensions, or when you're about to suggest one.
+---
+
+# Helping with extensions
+
+Extensions add what you can do: tools, skills and the know-how to use them (a Moodle classroom, a weather forecast, a lab). What's installed and what the catalogs offer come from `extensions_catalog`, read anew each time: never answer from memory. Answer in the language you reply in, briefly, with the exact command; commands are typed as written here. Without `extensions_catalog` among your tools, this agent has no folder for extensions and can't install any: say so, and suggest nothing.
+
+## What you never do
+
+- Install, enable, disable, configure or remove an extension yourself: the person does, with the commands below. You suggest and explain.
+- Ask for a secret (a token, a password) in the chat: what's typed there is kept in its history. Secrets are set in the agent's settings or from a terminal (`<agent> extension config <name> <key>`, which asks without showing it).
+- Suggest an extension the catalog didn't return, or one the person already declined in this conversation.
+
+## Suggesting one
+
+When the task needs what an extension does and it isn't installed, or it's off: one sentence with what it adds, what it needs (a program, a site, an account) and how to install it, then go on with what you can do without it.
+
+> The **weather** extension would give me today's forecast for your city; install it with `/extensions install weather@falkenslab` and tell me your city. Meanwhile, here's what I can plan without it…
+
+An extension that talks to a remote service sends what you give it there: say so when the person's data is involved.
+
+## Commands in the chat
+
+| Command | What it does |
+| --- | --- |
+| `/extensions` | What's running, what's off and why, what's installed |
+| `/extensions search <words>` | What the catalogs offer |
+| `/extensions install <name>@<marketplace>` | Installs one (one from a catalog that isn't the agent's own asks for confirmation) |
+| `/extensions reload` | Opens the session again with what's installed now, keeping the conversation |
+| `/extensions update [name]` | Updates one, or every one with a newer version |
+| `/extensions remove <name>` | Uninstalls one (`--delete-data` deletes its data too) |
+| `/extensions enable <name>` | Turns one on |
+| `/extensions disable <name>` | Turns one off, keeping it installed |
+| `/extensions config <name> [key=value…]` | Its options, and setting the ones that aren't secret |
+| `/extensions sign-in <name>` | Signs in to its remote service: gives the link to open |
+| `/extensions sign-out <name>` | Signs out of its remote service |
+| `/extensions trust` | Lets the workspace's extensions run |
+
+A new catalog (a marketplace) is added from a terminal: `<agent> extension marketplace add <owner/repo>`.
+
+## Why one is off
+
+`extensions_catalog` and `/extensions` give the reason; explain it and its remedy in plain words:
+
+- **An option without a value** (its site, its account): `/extensions config <name> <key>=<value>`, or the settings for a secret.
+- **A program missing on the computer** (Docker, ffmpeg): what it is, and the install command for this system the reason gives. The extension never installs it.
+- **It needs signing in**: `/extensions sign-in <name>`, then open the link.
+- **It requires another extension's capability**: install or enable the one that provides it.
+- **Its files changed** or **its workspace isn't trusted**: reinstall it, or `/extensions trust`.
+- **This agent's kit version is outside its range**: an update of the agent or of the extension.
+
+## What's new
+
+`extensions_catalog` with `refresh: true` fetches the catalogs again and says what's new: extensions added since the last copy, and newer versions of installed ones (`/extensions update`). Without network it answers from the copies on this computer and says how old they are.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkenslab/agent-kit",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Library for building an agent on top of the Claude Agent SDK",
   "author": "Francisco Vargas Ruiz",
   "license": "MIT",

package/schemas/marketplace-catalog.schema.json

@@ -80,6 +80,12 @@
           "type": "array",
           "items": { "$ref": "https://falkenslab.github.io/agent-kit/schemas/agent-kit-metadata.schema.json#/$defs/requirement" }
         },
+        "remote": {
+          "description": "The hosts its remote MCP servers talk to (type http or sse in its .mcp.json): what an agent sends there leaves the computer. Only when it has some.",
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
         "logo": { "description": "A URL anyone can load.", "$ref": "#/$defs/url" },
         "banner": { "description": "A URL anyone can load.", "$ref": "#/$defs/url" }
       }