@falkenslab/agent-kit 0.27.0 → 0.28.0

package/dist/chat/chatController.d.ts

@@ -62,6 +62,13 @@ export interface ChatSettings {
      * state's `panel`, answered with `answer()`.
      */
     panels?: "view" | "state";
+    /**
+     * Signing in to an extension (#72): `true` (the default) opens the link in this computer's
+     * browser (`openBrowser()`: not over SSH or without a display), `false` never does, and a
+     * function opens it the host's way (Electron's `shell.openExternal`), saying whether it did.
+     * The link is shown either way, on a line of its own, for another computer.
+     */
+    openBrowser?: boolean | ((url: string) => Promise<boolean>);
 }
 /** One tool call in the transcript. */
 export interface TranscriptCall {
@@ -270,9 +277,10 @@ export declare function createChatController(options: Options | SessionOpener, s
      * person. The running session is untouched: it's there in a new conversation, or with `reopen()`.
      */
     /**
-     * Signs in to an installed extension's remote servers (#61): gives the person the links (never
-     * opens a browser), then says when the sign-in finishes. With `callbackUrl`, the address the
-     * browser ended on (from another computer), finishes it instead.
+     * Signs in to an installed extension's remote servers (#61): opens each link in this computer's
+     * browser as `openBrowser` says (#72) and shows it on a line of its own, for another computer,
+     * then says when the sign-in finishes. With `callbackUrl`, the address the browser ended on
+     * (from another computer), finishes it instead.
      */
     signInExtension(name: string, callbackUrl?: string): Promise<SignIn>;
     /** Signs out of an installed extension's remote servers (#61). */

package/dist/chat/chatController.js

@@ -16,6 +16,7 @@ import { extensionOptionStates, listInstalled, removeExtension as removeInstalle
 import { extensionCatalog as readCatalog, installExtension as installFromCatalog, needsConfirmation, updateExtension as updateFromCatalog } from "../core/extensionCatalog.js";
 import { capHistory, loadHistory, saveHistory, slashCommandToken } from "./history.js";
 import { firstRun, openSession, runFolderOf, runLabel } from "./runs.js";
+import { openBrowser } from "../core/openBrowser.js";
 const DEFAULT_EXIT_COMMANDS = ["/exit", "/quit"];
 const DEFAULT_HISTORY_LIMIT = 100;
 const DEFAULT_PROMPT_LABEL = "\n> ";
@@ -600,9 +601,10 @@ export async function createChatController(options, settings = {}) {
          * person. The running session is untouched: it's there in a new conversation, or with `reopen()`.
          */
         /**
-         * Signs in to an installed extension's remote servers (#61): gives the person the links (never
-         * opens a browser), then says when the sign-in finishes. With `callbackUrl`, the address the
-         * browser ended on (from another computer), finishes it instead.
+         * Signs in to an installed extension's remote servers (#61): opens each link in this computer's
+         * browser as `openBrowser` says (#72) and shows it on a line of its own, for another computer,
+         * then says when the sign-in finishes. With `callbackUrl`, the address the browser ended on
+         * (from another computer), finishes it instead.
          */
         async signInExtension(name, callbackUrl) {
             const auth = current.extensionAuth;
@@ -612,8 +614,13 @@ export async function createChatController(options, settings = {}) {
             else if (result.status === "signed-in")
                 notice(callbackUrl ? t().extensionSignedIn(name) : t().extensionAlreadySignedIn(name));
             else {
-                for (const link of result.links)
-                    notice(t().extensionSignInOpen(name, link.url));
+                const open = settings.openBrowser === false ? undefined : typeof settings.openBrowser === "function" ? settings.openBrowser : openBrowser;
+                for (const link of result.links) {
+                    const opened = open ? await open(link.url).catch(() => false) : false;
+                    notice(opened ? t().extensionSignInOpened(name) : t().extensionSignInOpen(name));
+                    // Alone on its line: a view shows it whole (a terminal link, #72), and it's copied whole.
+                    notice(link.url);
+                }
                 notice(t().extensionSignInPaste(name));
                 // Waits in the background: the person signs in in their browser, whenever they do.
                 void auth.connected(name, 5 * 60_000).then((done) => {

package/dist/core/messages/de.js

@@ -53,7 +53,8 @@ export const de = {
     extensionLacks: (name, what) => `(${name}: ${what})`,
     extensionTalksTo: (name, hosts) => `(${name} spricht mit ${hosts}: was dein Agent dorthin sendet, verlässt diesen Computer)`,
     extensionNeedsSignIn: (name) => `${name} braucht deine Anmeldung: /extensions sign-in ${name}`,
-    extensionSignInOpen: (name, url) => `(zum Anmelden bei ${name} öffne ${url} : sobald du dort fertig bist, ist sie hier verbunden)`,
+    extensionSignInOpen: (name) => `(zum Anmelden bei ${name} öffne diesen Link; sobald du dort fertig bist, ist sie hier verbunden:)`,
+    extensionSignInOpened: (name) => `(Anmeldung bei ${name} in deinem Browser; sobald du dort fertig bist, ist sie hier verbunden. Der Link, für einen anderen Browser:)`,
     extensionSignInPaste: (name) => `(auf einem anderen Computer? Füge die Adresse ein, bei der der Browser landet: /extensions sign-in ${name} <diese Adresse>)`,
     extensionSignedIn: (name) => `(bei ${name} angemeldet: ihre Werkzeuge sind bereit)`,
     extensionSignInWaiting: (name) => `(warte noch auf die Anmeldung bei ${name}; /extensions sign-in ${name} gibt den Link erneut)`,

package/dist/core/messages/en.d.ts

@@ -73,7 +73,9 @@ export interface Messages {
     /** In /extensions: a running extension whose remote server needs the person to sign in. */
     extensionNeedsSignIn(name: string): string;
     /** The link to sign in to an extension's remote server. */
-    extensionSignInOpen(name: string, url: string): string;
+    /** Before the sign-in link, on its own line next (#72): when the browser couldn't be opened, and when it was. */
+    extensionSignInOpen(name: string): string;
+    extensionSignInOpened(name: string): string;
     /** How to finish signing in from another computer. */
     extensionSignInPaste(name: string): string;
     extensionSignedIn(name: string): string;

package/dist/core/messages/en.js

@@ -53,7 +53,8 @@ export const en = {
     extensionLacks: (name, what) => `(${name} ${what})`,
     extensionTalksTo: (name, hosts) => `(${name} talks to ${hosts}: what your agent sends there leaves this computer)`,
     extensionNeedsSignIn: (name) => `${name} needs you to sign in: /extensions sign-in ${name}`,
-    extensionSignInOpen: (name, url) => `(to sign in to ${name}, open ${url} : when you're done there, it's connected here)`,
+    extensionSignInOpen: (name) => `(to sign in to ${name}, open this link; when you're done there, it's connected here:)`,
+    extensionSignInOpened: (name) => `(signing in to ${name} in your browser; when you're done there, it's connected here. The link, for another browser:)`,
     extensionSignInPaste: (name) => `(on another computer? Paste the address the browser ends on: /extensions sign-in ${name} <that address>)`,
     extensionSignedIn: (name) => `(signed in to ${name}: its tools are ready)`,
     extensionSignInWaiting: (name) => `(still waiting for the sign-in to ${name}; /extensions sign-in ${name} gives the link again)`,

package/dist/core/messages/es.js

@@ -53,7 +53,8 @@ export const es = {
     extensionLacks: (name, what) => `(${name}: ${what})`,
     extensionTalksTo: (name, hosts) => `(${name} habla con ${hosts}: lo que tu agente le envíe sale de este ordenador)`,
     extensionNeedsSignIn: (name) => `${name} necesita que inicies sesión: /extensions sign-in ${name}`,
-    extensionSignInOpen: (name, url) => `(para iniciar sesión en ${name}, abre ${url} : cuando termines allí, queda conectada aquí)`,
+    extensionSignInOpen: (name) => `(para iniciar sesión en ${name}, abre este enlace; cuando termines allí, queda conectada aquí:)`,
+    extensionSignInOpened: (name) => `(iniciando sesión en ${name} en tu navegador; cuando termines allí, queda conectada aquí. El enlace, para otro navegador:)`,
     extensionSignInPaste: (name) => `(¿en otro ordenador? Pega la dirección en la que acaba el navegador: /extensions sign-in ${name} <esa dirección>)`,
     extensionSignedIn: (name) => `(sesión iniciada en ${name}: sus herramientas están listas)`,
     extensionSignInWaiting: (name) => `(sigo esperando el inicio de sesión en ${name}; /extensions sign-in ${name} vuelve a dar el enlace)`,

package/dist/core/messages/fr.js

@@ -53,7 +53,8 @@ export const fr = {
     extensionLacks: (name, what) => `(${name} : ${what})`,
     extensionTalksTo: (name, hosts) => `(${name} échange avec ${hosts} : ce que votre agent y envoie quitte cet ordinateur)`,
     extensionNeedsSignIn: (name) => `${name} a besoin que vous vous connectiez : /extensions sign-in ${name}`,
-    extensionSignInOpen: (name, url) => `(pour vous connecter à ${name}, ouvrez ${url} : une fois terminé là-bas, elle est connectée ici)`,
+    extensionSignInOpen: (name) => `(pour vous connecter à ${name}, ouvrez ce lien ; une fois terminé là-bas, elle est connectée ici :)`,
+    extensionSignInOpened: (name) => `(connexion à ${name} dans votre navigateur ; une fois terminé là-bas, elle est connectée ici. Le lien, pour un autre navigateur :)`,
     extensionSignInPaste: (name) => `(sur un autre ordinateur ? Collez l'adresse où le navigateur arrive : /extensions sign-in ${name} <cette adresse>)`,
     extensionSignedIn: (name) => `(connecté à ${name} : ses outils sont prêts)`,
     extensionSignInWaiting: (name) => `(toujours en attente de la connexion à ${name} ; /extensions sign-in ${name} redonne le lien)`,

package/dist/core/npxPackages.js

@@ -47,8 +47,12 @@ async function packageBin(dir, name) {
     const bundled = json.bundleDependencies ?? json.bundledDependencies;
     const declared = Object.keys({ ...json.dependencies, ...json.optionalDependencies });
     const missing = bundled === true ? [] : declared.filter((dependency) => !(Array.isArray(bundled) && bundled.includes(dependency)));
+    // Only package.json is read (#71): one bundled into the program but still in `dependencies`
+    // looks missing too, so the message says both ways out.
     if (missing.length)
-        return { problem: `has dependencies it doesn't bring (${missing.join(", ")}): the kit installs none, so a package must bundle them, or list them in bundleDependencies` };
+        return {
+            problem: `declares dependencies it doesn't bring (${missing.join(", ")}): the kit installs none. If they're bundled into its program, move them to devDependencies; otherwise list them in bundleDependencies`,
+        };
     const scripts = ["preinstall", "install", "postinstall"].filter((script) => json.scripts?.[script]);
     if (scripts.length)
         return { problem: `has install scripts (${scripts.join(", ")}), which the kit never runs` };

package/dist/core/openBrowser.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Whether a browser can be opened on this computer (#72): not over SSH, nor on Linux without a
+ * display (a server, a container). Elsewhere the desktop is there.
+ */
+export declare function canOpenBrowser(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/**
+ * Opens an `http(s)` address in this computer's browser, with the system's own opener and no
+ * shell (an OAuth link is full of `&`, which `cmd /c start` would cut): `rundll32` on Windows,
+ * `open` on macOS, `xdg-open` elsewhere. False when it can't (`canOpenBrowser()`, another kind
+ * of address, no opener): then the person is given the link only.
+ */
+export declare function openBrowser(url: string): Promise<boolean>;

package/dist/core/openBrowser.js

@@ -0,0 +1,36 @@
+import { spawn } from "node:child_process";
+/**
+ * Whether a browser can be opened on this computer (#72): not over SSH, nor on Linux without a
+ * display (a server, a container). Elsewhere the desktop is there.
+ */
+export function canOpenBrowser(env = process.env, platform = process.platform) {
+    if (env.SSH_CONNECTION || env.SSH_TTY || env.SSH_CLIENT)
+        return false;
+    if (platform === "win32" || platform === "darwin")
+        return true;
+    return Boolean(env.DISPLAY || env.WAYLAND_DISPLAY);
+}
+/**
+ * Opens an `http(s)` address in this computer's browser, with the system's own opener and no
+ * shell (an OAuth link is full of `&`, which `cmd /c start` would cut): `rundll32` on Windows,
+ * `open` on macOS, `xdg-open` elsewhere. False when it can't (`canOpenBrowser()`, another kind
+ * of address, no opener): then the person is given the link only.
+ */
+export async function openBrowser(url) {
+    if (!/^https?:\/\//i.test(url) || !canOpenBrowser())
+        return false;
+    const [command, args] = process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]] : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+    return await new Promise((resolve) => {
+        try {
+            const child = spawn(command, args, { detached: true, stdio: "ignore", windowsHide: true });
+            child.once("error", () => resolve(false));
+            child.once("spawn", () => {
+                child.unref();
+                resolve(true);
+            });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}

package/dist/index.d.ts

@@ -52,6 +52,7 @@ export { createSaveToSourcesServer, sourcesPromptSection, type SourceToolsOption
 export { runChatTui, type ChatTuiOptions } from "./tui/chatTui.js";
 export type { SessionOpener } from "./chat/runs.js";
 export { createChatController, type ChatController, type ChatSettings, type ChatState, type ChatEvent, type ChatPanel, type ChatQuestion, type TranscriptEntry, type TranscriptCall, type NoticeTone, } from "./chat/chatController.js";
+export { openBrowser, canOpenBrowser } from "./core/openBrowser.js";
 export { createConsoleRenderer, type ConsoleRenderer, type ConsoleRendererOptions } from "./tui/consoleRenderer.js";
 export { runChatInk, type InkChatOptions, type HeaderInfo } from "./tui/ink/runChatInk.js";
 export type { ToolPhrase, ToolDetail, ResultFormatter } from "./tui/ink/toolGroup.js";

package/dist/index.js

@@ -53,6 +53,7 @@ export { createManualLoginServer } from "./core/tools/manualLogin.js";
 export { createSaveToSourcesServer, sourcesPromptSection } from "./extensions/sources/tools.js";
 export { runChatTui } from "./tui/chatTui.js";
 export { createChatController, } from "./chat/chatController.js";
+export { openBrowser, canOpenBrowser } from "./core/openBrowser.js";
 export { createConsoleRenderer } from "./tui/consoleRenderer.js";
 export { runChatInk } from "./tui/ink/runChatInk.js";
 export { createProgressView } from "./tui/ink/progressView.js";

package/dist/tui/chatTui.d.ts

@@ -4,6 +4,7 @@ import type { AgentEvent } from "../core/runner.js";
 import { type Theme } from "./theme.js";
 import type { ToolLabels } from "../core/toolLabels.js";
 import { type SessionOpener } from "../chat/runs.js";
+import { type ChatSettings } from "../chat/chatController.js";
 export { capHistory, loadHistory, saveHistory, slashCommandToken } from "../chat/history.js";
 /** Options of the chats (`runChatTui()`, and `runChatInk()` through `InkChatOptions`). */
 export interface ChatTuiOptions {
@@ -14,6 +15,8 @@ export interface ChatTuiOptions {
      * own domain-specific tools (Playwright's `browser_*`, etc.).
      */
     formatAction?: (toolName: string, input: unknown) => string;
+    /** Signing in to an extension: whether its link opens in this computer's browser (the default), or how (see `ChatSettings.openBrowser`, #72). */
+    openBrowser?: ChatSettings["openBrowser"];
     /** Printed once before the first prompt, if given. */
     welcomeMessage?: string;
     /** Shown before the cursor at each prompt. */

package/dist/tui/chatTui.js

@@ -8,6 +8,7 @@ import { applyTheme } from "./theme.js";
 import { createConsoleRenderer } from "./consoleRenderer.js";
 import { runDate } from "../chat/runs.js";
 import { createChatController } from "../chat/chatController.js";
+import { linkedNotice } from "./hyperlink.js";
 export { capHistory, loadHistory, saveHistory, slashCommandToken } from "../chat/history.js";
 const DEFAULT_PROMPT_LABEL = "\n> ";
 const DEFAULT_EXIT_COMMANDS = ["/exit", "/quit"];
@@ -75,6 +76,7 @@ export async function runChatTui(options, tuiOptions = {}) {
         modeControl: tuiOptions.modeControl,
         toolLabels: tuiOptions.toolLabels,
         formatAction: tuiOptions.formatAction,
+        ...(tuiOptions.openBrowser !== undefined ? { openBrowser: tuiOptions.openBrowser } : {}),
         // Nothing here shows them.
         promptSuggestions: false,
         // /resume: a numbered list, and a number typed.
@@ -131,7 +133,8 @@ export async function runChatTui(options, tuiOptions = {}) {
                     renderer.render(event.event);
                 return;
             case "notice":
-                writeLine(toned(event.text, event.tone));
+                // An address alone (a sign-in link) as a terminal link (#72).
+                writeLine(toned(linkedNotice(event.text), event.tone));
                 return;
             case "turn-start":
                 renderer.startTurn();

package/dist/tui/extensionCommand.js

@@ -59,8 +59,10 @@ export async function runExtensionCommand(argv, options) {
     const ask = options.ask ?? askOnTerminal;
     const askSecret = options.askSecret ?? (options.ask ? options.ask : askSecretOnTerminal);
     /**
-     * After installing `name` into `dir`: its options from `--set`, then asked for each still
-     * without a value (on a terminal; none without one), saying which required ones are left.
+     * After installing `name` into `dir`: its options from `--set`, saved first so a prompt cut
+     * short loses none (#73), then asked for each still without a value, saying which required ones
+     * are left. Never asked with `--yes`, nor without a terminal unless the host asks itself (`ask`):
+     * a default stays, an optional one stays unset.
      */
     const configure = async (name, dir) => {
         const installed = (await listInstalled(options.dirs)).find((extension) => extension.name === name && extension.scopeDir === dir);
@@ -74,17 +76,24 @@ export async function runExtensionCommand(argv, options) {
                 throw new Error(`--set takes key=value: "${pair}"`);
             typed[pair.slice(0, at)] = pair.slice(at + 1);
         }
+        if (Object.keys(typed).length)
+            await setExtensionOptions(installed, name, typed);
         const states = await describeOptionStates(installed);
+        const canAsk = !flag("yes") && (options.ask !== undefined || process.stdin.isTTY === true);
+        const asked = {};
         for (const [key, option] of Object.entries(declared)) {
+            if (!canAsk)
+                break;
             if (key in typed || states.get(key))
                 continue;
             const question = `${option.title}${option.required ? "" : " (optional)"}${option.default !== undefined ? ` [${String(option.default)}]` : ""}: ${option.description}\n  ${key} = `;
             const answer = (await (option.sensitive ? askSecret : ask)(question)).trim();
             if (answer)
-                typed[key] = answer;
+                asked[key] = answer;
         }
-        if (Object.keys(typed).length)
-            await setExtensionOptions(installed, name, typed);
+        if (Object.keys(asked).length)
+            await setExtensionOptions(installed, name, asked);
+        Object.assign(typed, asked);
         const missing = Object.entries(declared).filter(([key, option]) => option.required && !(key in typed) && !states.get(key) && option.default === undefined).map(([key]) => key);
         if (missing.length)
             write(`It stays off until ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} set: \`${command} extension config ${name} ${missing[0]}\`.`);

package/dist/tui/hyperlink.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Terminal hyperlinks (OSC 8, #72): a long address the full-screen chat wraps stays one link,
+ * since every row it's cut into opens it whole (`wrap-ansi` reopens the link on each row).
+ */
+/**
+ * Whether the terminal shows OSC 8 links, from what it says about itself: Windows Terminal,
+ * VS Code's, iTerm2, WezTerm, Konsole, a recent VTE (GNOME's), DomTerm. `FORCE_HYPERLINK=1` or `0`
+ * decides. Elsewhere none: a terminal that doesn't know the sequence may print it.
+ */
+export declare function supportsHyperlinks(env?: NodeJS.ProcessEnv, isTTY?: boolean): boolean;
+/** `text` as a link to `url` (OSC 8). */
+export declare function hyperlink(url: string, text?: string): string;
+/** A notice that is an address alone (a sign-in link, #72) as a link when the terminal shows them; any other text as it is. */
+export declare function linkedNotice(text: string, linked?: boolean): string;

package/dist/tui/hyperlink.js

@@ -0,0 +1,28 @@
+/**
+ * Terminal hyperlinks (OSC 8, #72): a long address the full-screen chat wraps stays one link,
+ * since every row it's cut into opens it whole (`wrap-ansi` reopens the link on each row).
+ */
+/**
+ * Whether the terminal shows OSC 8 links, from what it says about itself: Windows Terminal,
+ * VS Code's, iTerm2, WezTerm, Konsole, a recent VTE (GNOME's), DomTerm. `FORCE_HYPERLINK=1` or `0`
+ * decides. Elsewhere none: a terminal that doesn't know the sequence may print it.
+ */
+export function supportsHyperlinks(env = process.env, isTTY = process.stdout.isTTY === true) {
+    if (env.FORCE_HYPERLINK !== undefined)
+        return env.FORCE_HYPERLINK !== "0";
+    if (!isTTY)
+        return false;
+    if (env.WT_SESSION || env.KONSOLE_VERSION || env.DOMTERM)
+        return true;
+    if (["vscode", "iTerm.app", "WezTerm"].includes(env.TERM_PROGRAM ?? ""))
+        return true;
+    return Number(env.VTE_VERSION ?? 0) >= 5000;
+}
+/** `text` as a link to `url` (OSC 8). */
+export function hyperlink(url, text = url) {
+    return `\x1b]8;;${url}\x07${text}\x1b]8;;\x07`;
+}
+/** A notice that is an address alone (a sign-in link, #72) as a link when the terminal shows them; any other text as it is. */
+export function linkedNotice(text, linked = supportsHyperlinks()) {
+    return linked && /^https?:\/\/\S+$/.test(text) ? hyperlink(text) : text;
+}

package/dist/tui/ink/runChatInk.js

@@ -6,6 +6,7 @@ import { Select } from "@inkjs/ui";
 import { getInteractionPort, setInteractionPort } from "../../core/interaction.js";
 import { runChatTui } from "../chatTui.js";
 import { createChatController } from "../../chat/chatController.js";
+import { linkedNotice } from "../hyperlink.js";
 import * as ui from "../ui.js";
 import { t } from "../../core/messages/index.js";
 import { applyLanguage } from "../language.js";
@@ -197,6 +198,7 @@ export async function runChatInk(options, tuiOptions = {}) {
         toolLabels: tuiOptions.toolLabels,
         formatAction: tuiOptions.formatAction,
         toolPhrase: tuiOptions.toolPhrase,
+        ...(tuiOptions.openBrowser !== undefined ? { openBrowser: tuiOptions.openBrowser } : {}),
         promptSuggestions: tuiOptions.promptSuggestions ?? true,
         // The /resume list in place of the prompt.
         pick: (title, choices) => input.pick(title, choices),
@@ -241,7 +243,8 @@ export async function runChatInk(options, tuiOptions = {}) {
                 model.note(userLine(event.text), "user");
                 return;
             case "notice":
-                model.writeLine(toned(event.text, event.tone));
+                // An address alone (a sign-in link) as a terminal link, whole however it wraps (#72).
+                model.writeLine(toned(linkedNotice(event.text), event.tone));
                 return;
             case "turn-start":
                 input.setSuggestion(null);

package/package.json

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