@4onstudios/iris-agent 0.1.0 → 0.2.1

package/README.md

@@ -142,15 +142,52 @@ standard error. Each ACP process is bound to the workspace supplied at startup.
 To switch workspaces, close the process and respawn `iris-agent` with the new
 `--workspace` path.
 
+When the current directory is the target workspace, `--workspace` is optional:
+
+```sh
+OPENROUTER_API_KEY=... npx @4onstudios/iris-agent@latest --acp
+```
+
+If the selected model's credentials are missing, Iris Agent stops before opening
+the ACP connection and prints the required environment variable, a terminal
+command, and a ready-to-paste VS Code ACP Client configuration. Configure API
+keys in `acp.agents.<name>.env`; do not put them in the argument list:
+
+```json
+{
+  "acp.agents": {
+    "Iris Agent": {
+      "command": "npx",
+      "args": ["@4onstudios/iris-agent@latest", "--acp"],
+      "env": {
+        "OPENROUTER_API_KEY": "your-openrouter-api-key"
+      }
+    }
+  }
+}
+```
+
+Use `--modelId` to select a direct provider: `openai/gpt-4o` with
+`OPENAI_API_KEY`, `anthropic/claude-sonnet-4-5` with `ANTHROPIC_API_KEY`,
+`google/gemini-2.5-pro` with `GOOGLE_GENERATIVE_AI_API_KEY`, or
+`huggingface/...` with `HF_TOKEN`. Local `ollama/<model>` sessions do not need
+a cloud API key.
+
+Iris Agent advertises ACP session loading and listing, so
+[VS Code ACP Client](https://github.com/formulahendry/vscode-acp) can display
+and restore persisted conversations for the current workspace. It also returns
+the per-session model configuration option required by the extension's composer
+controls.
+
 ## CLI Usage
 
 ```sh
-iris-agent --workspace <path> [--acp | --chat] [--modelId <model>]
+iris-agent [--workspace <path>] [--acp | --chat] [--modelId <model>]
 ```
 
 **Options:**
 
-- `--workspace` (required, `-w`) - Path to the workspace/project root
+- `--workspace` (`-w`) - Path to the workspace/project root; defaults to the current working directory
 - `--acp` (`-a`) - Start ACP protocol server (stdio-based)
 - `--chat` (`-c`) - Start interactive chat mode
 - `--modelId` - Model identifier used for chat/ACP sessions (default: `openrouter/openai/gpt-4o` or `MODEL_ID` / `OPENROUTER_MODEL` env vars)
@@ -169,6 +206,9 @@ npm run cli -- --workspace . --chat --modelId openrouter/anthropic/claude-3.7-so
 # ACP server for IDE integration
 npm run cli -- --workspace . --acp
 
+# ACP server from the current workspace
+npx @4onstudios/iris-agent@latest --acp
+
 # ACP server with custom default model
 npm run cli -- --workspace . --acp --modelId openrouter/openai/gpt-4o
 
@@ -666,14 +706,9 @@ The project logo is available at
 community references. Keep the logo unchanged when using it as the project
 mark.
 
-## Package publishing
+## Package
 
-The package is configured for public npm publication:
-
-```sh
-npm login
-npm publish
-```
+The published package is available on [npm](https://www.npmjs.com/package/@4onstudios/iris-agent).
 
 Yarn users can install the published package with:
 
@@ -681,10 +716,4 @@ Yarn users can install the published package with:
 yarn global add @4onstudios/iris-agent
 ```
 
-Publishing requires access to the `@4onstudios` npm scope. The package is
-configured with public access, but npm credentials and organization
-permissions must be supplied by the publisher.
-
-See [RELEASING.md](./RELEASING.md) for npm publication and versioning steps.
-
 This project is released under the [MIT License](LICENSE).

package/dist/api/acp/acpServer.js

@@ -9,7 +9,18 @@ import { executeCommand } from "../core/agent/tools/executeCommand.js";
 import { getSlashCommandDescriptors, isSlashCommandsFeatureEnabled, } from "../helpers/slashCommands.js";
 import { extractTokenUsageFromChunkPayload, mergeTokenUsage, } from "../helpers/tokenUsage.js";
 const DEFAULT_MAX_STEPS = 50;
+const MAX_CONCURRENT_SESSION_LOADS = 16;
 const CHAT_SESSIONS_DIR = path.join(os.homedir(), ".iris", "chat-sessions");
+const hasPersistedSessionCwd = (persisted) => typeof persisted?.cwd === "string" && persisted.cwd.length > 0;
+const getPersistedSessionTitle = (persisted) => typeof persisted?.title === "string" ? persisted.title : undefined;
+const getPersistedSessionUpdatedAt = (persisted) => {
+    if (typeof persisted.updatedAt !== "number" &&
+        typeof persisted.updatedAt !== "string") {
+        return undefined;
+    }
+    const timestamp = new Date(persisted.updatedAt);
+    return Number.isNaN(timestamp.getTime()) ? undefined : timestamp.toISOString();
+};
 const isSafeChatSessionId = (sessionId) => /^[A-Za-z0-9._:-]+$/.test(sessionId);
 const getChatSessionPath = (sessionId) => path.join(CHAT_SESSIONS_DIR, `${sessionId}.json`);
 const loadPersistedChatSession = async (sessionId) => {
@@ -26,13 +37,33 @@ const loadPersistedChatSession = async (sessionId) => {
         return undefined;
     }
 };
-const savePersistedChatSession = async (sessionId, messages, existing) => {
+const loadPersistedChatSessions = async (sessionIds) => {
+    const loaded = new Array(sessionIds.length);
+    let nextIndex = 0;
+    const worker = async () => {
+        while (nextIndex < sessionIds.length) {
+            const index = nextIndex;
+            nextIndex += 1;
+            const sessionId = sessionIds[index];
+            if (sessionId) {
+                loaded[index] = await loadPersistedChatSession(sessionId);
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(MAX_CONCURRENT_SESSION_LOADS, sessionIds.length) }, worker));
+    return loaded.flatMap((persisted, index) => {
+        const sessionId = sessionIds[index];
+        return persisted && sessionId ? [{ sessionId, persisted }] : [];
+    });
+};
+const savePersistedChatSession = async (sessionId, messages, session, existing) => {
     if (!isSafeChatSessionId(sessionId))
         return;
     const timestamp = Date.now();
     const payload = {
         id: sessionId,
-        title: existing?.title,
+        cwd: path.resolve(session.cwd),
+        title: session.title ?? getPersistedSessionTitle(existing),
         createdAt: existing?.createdAt ?? timestamp,
         updatedAt: timestamp,
         messages,
@@ -92,6 +123,18 @@ export function assertAcpWorkspace(params, boundWorkspaceRoot) {
         throw new Error(`This ACP process is bound to '${path.resolve(boundWorkspaceRoot)}'. Close it and respawn iris-agent with --workspace '${path.resolve(requestedWorkspace)}' to switch workspaces.`);
     }
 }
+const resolveAcpWorkspace = (params, boundWorkspaceRoot) => {
+    if (boundWorkspaceRoot) {
+        assertAcpWorkspace(params, boundWorkspaceRoot);
+        return boundWorkspaceRoot;
+    }
+    const requestedWorkspace = typeof params?.workspaceRoot === "string"
+        ? params.workspaceRoot
+        : typeof params?.cwd === "string"
+            ? params.cwd
+            : undefined;
+    return path.resolve(requestedWorkspace || process.cwd());
+};
 const toPromptText = (prompt) => prompt
     .map((block) => {
     if (block.type === "text")
@@ -184,23 +227,34 @@ export const createAcpAgentApp = (agentProvider, workspaceRoot) => {
         })
             .catch(() => undefined);
     };
+    const getConfigOptions = (modelId) => {
+        const currentModel = modelId || "default";
+        return [
+            {
+                id: "model",
+                name: "Model",
+                type: "select",
+                category: "model",
+                currentValue: currentModel,
+                options: [{ value: currentModel, name: currentModel }],
+            },
+        ];
+    };
     return acp
         .agent({ name: "iris-agent" })
         .onRequest(acp.methods.agent.initialize, async () => ({
         protocolVersion: acp.PROTOCOL_VERSION,
         agentCapabilities: {
             loadSession: true,
-            sessionCapabilities: { close: {} },
+            sessionCapabilities: { close: {}, list: {} },
         },
         agentInfo: {
             name: "iris-agent",
-            version: "0.1.0",
+            version: "0.2.0",
         },
     }))
         .onRequest(acp.methods.agent.session.new, async (ctx) => {
-        if (boundWorkspaceRoot) {
-            assertAcpWorkspace({ cwd: ctx.params.cwd }, boundWorkspaceRoot);
-        }
+        const sessionWorkspace = resolveAcpWorkspace(ctx.params, boundWorkspaceRoot);
         const irisMeta = readIrisMeta(ctx.params._meta);
         const requestedModel = irisMeta.modelId ||
             (typeof ctx.params.modelId === "string"
@@ -210,18 +264,19 @@ export const createAcpAgentApp = (agentProvider, workspaceRoot) => {
             ? irisMeta.chatSessionId
             : randomUUID();
         sessions.set(sessionId, {
-            cwd: boundWorkspaceRoot || ctx.params.cwd,
+            cwd: sessionWorkspace,
             modelId: requestedModel,
             history: [],
         });
         await notifyAvailableCommands(ctx, sessionId);
-        return { sessionId };
+        return {
+            sessionId,
+            configOptions: getConfigOptions(requestedModel),
+        };
     })
         .onRequest(acp.methods.agent.session.load, async (ctx) => {
         const sessionId = ctx.params.sessionId;
-        if (boundWorkspaceRoot) {
-            assertAcpWorkspace({ cwd: ctx.params.cwd }, boundWorkspaceRoot);
-        }
+        const requestedWorkspace = resolveAcpWorkspace(ctx.params, boundWorkspaceRoot);
         const irisMeta = readIrisMeta(ctx.params._meta);
         const requestedModel = irisMeta.modelId ||
             (typeof ctx.params.modelId === "string"
@@ -231,10 +286,18 @@ export const createAcpAgentApp = (agentProvider, workspaceRoot) => {
         if (!persisted) {
             throw new Error(`No persisted chat session found for '${sessionId}'`);
         }
+        const sessionWorkspace = hasPersistedSessionCwd(persisted)
+            ? path.resolve(persisted.cwd)
+            : requestedWorkspace;
+        if (boundWorkspaceRoot &&
+            path.resolve(sessionWorkspace) !== path.resolve(boundWorkspaceRoot)) {
+            throw new Error(`Persisted ACP session '${sessionId}' belongs to '${sessionWorkspace}', not this process's bound workspace '${boundWorkspaceRoot}'.`);
+        }
         const history = persisted.messages.slice();
         sessions.set(sessionId, {
-            cwd: boundWorkspaceRoot || ctx.params.cwd,
+            cwd: sessionWorkspace,
             modelId: requestedModel,
+            title: getPersistedSessionTitle(persisted),
             history,
         });
         for (const message of history) {
@@ -247,7 +310,37 @@ export const createAcpAgentApp = (agentProvider, workspaceRoot) => {
             });
         }
         await notifyAvailableCommands(ctx, sessionId);
-        return {};
+        return { configOptions: getConfigOptions(requestedModel) };
+    })
+        .onRequest(acp.methods.agent.session.list, async (ctx) => {
+        const requestedCwd = resolveAcpWorkspace(ctx.params, boundWorkspaceRoot);
+        let entries;
+        try {
+            entries = await fs.readdir(CHAT_SESSIONS_DIR, {
+                withFileTypes: true,
+            });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+            return { sessions: [] };
+        }
+        const persistedSessions = (await loadPersistedChatSessions(entries
+            .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+            .map((entry) => entry.name.slice(0, -".json".length))))
+            .filter(({ persisted }) => !hasPersistedSessionCwd(persisted) ||
+            path.resolve(persisted.cwd) === requestedCwd)
+            .map(({ sessionId, persisted }) => ({
+            sessionId,
+            cwd: hasPersistedSessionCwd(persisted)
+                ? path.resolve(persisted.cwd)
+                : requestedCwd,
+            title: getPersistedSessionTitle(persisted),
+            updatedAt: getPersistedSessionUpdatedAt(persisted),
+        }));
+        persistedSessions.sort((left, right) => (right.updatedAt || "").localeCompare(left.updatedAt || ""));
+        return { sessions: persistedSessions };
     })
         .onRequest(acp.methods.agent.session.setConfigOption, async (ctx) => {
         const sessionId = ctx.params.sessionId;
@@ -265,20 +358,7 @@ export const createAcpAgentApp = (agentProvider, workspaceRoot) => {
                 session.modelId = undefined;
             }
         }
-        const currentModel = session.modelId || "default";
-        const configOptions = [
-            {
-                id: "model",
-                name: "Model",
-                type: "select",
-                category: "model",
-                currentValue: currentModel,
-                options: [
-                    { value: currentModel, name: currentModel },
-                ],
-            },
-        ];
-        return { configOptions };
+        return { configOptions: getConfigOptions(session.modelId) };
     })
         .onRequest(acp.methods.agent.session.prompt, async (ctx) => {
         const sessionId = ctx.params.sessionId;
@@ -305,10 +385,13 @@ export const createAcpAgentApp = (agentProvider, workspaceRoot) => {
             session.history.push({ role: "user", content: promptText });
         }
         const persistTurn = async (assistantText) => {
+            if (promptText && !session.title) {
+                session.title = promptText.replace(/\s+/g, " ").slice(0, 120);
+            }
             if (assistantText) {
                 session.history.push({ role: "assistant", content: assistantText });
             }
-            await savePersistedChatSession(sessionId, session.history, await loadPersistedChatSession(sessionId));
+            await savePersistedChatSession(sessionId, session.history, session, await loadPersistedChatSession(sessionId));
         };
         const turnSignal = activeTurn.abortController.signal;
         if (sessions.get(sessionId) !== session || turnSignal.aborted) {
@@ -809,6 +892,6 @@ export async function startAcpServer(runtimeAgentOrFactory, workspaceRoot) {
     const output = Writable.toWeb(process.stdout);
     const input = Readable.toWeb(process.stdin);
     const connection = createAcpAgentApp(runtimeAgentOrFactory, workspaceRoot).connect(acp.ndJsonStream(output, input));
-    console.error("ACP agent ready: iris-agent@0.1.0 (stdio)");
+    console.error("ACP agent ready: iris-agent@0.2.0 (stdio)");
     await connection.closed;
 }

package/dist/api/acp/providerSetup.d.ts

@@ -0,0 +1,3 @@
+type Environment = Record<string, string | undefined>;
+export declare const getMissingProviderSetup: (modelId: string, environment?: Environment) => string | undefined;
+export {};

package/dist/api/acp/providerSetup.js

@@ -0,0 +1,134 @@
+const getConfiguredKey = (environment, keys) => keys.some((key) => Boolean(environment[key]?.trim()));
+const getRequiredProvider = (modelId, environment) => {
+    const normalizedModelId = modelId.endsWith("-other")
+        ? modelId.slice(0, -"-other".length)
+        : modelId;
+    if (normalizedModelId.startsWith("ollama/") ||
+        normalizedModelId.startsWith("local/")) {
+        return undefined;
+    }
+    if (normalizedModelId.startsWith("huggingface/") ||
+        normalizedModelId.endsWith(":fireworks-ai")) {
+        return getConfiguredKey(environment, ["HF_TOKEN"])
+            ? undefined
+            : {
+                credential: "HF_TOKEN",
+                modelExample: "huggingface/Qwen/Qwen2.5-Coder-32B-Instruct",
+                description: "a Hugging Face Inference Providers token",
+            };
+    }
+    if (normalizedModelId.startsWith("openrouter/")) {
+        return getConfiguredKey(environment, ["OPENROUTER_API_KEY"])
+            ? undefined
+            : {
+                credential: "OPENROUTER_API_KEY",
+                modelExample: "openrouter/openai/gpt-4o",
+                description: "an OpenRouter API key",
+            };
+    }
+    if (normalizedModelId.startsWith("openai/")) {
+        return getConfiguredKey(environment, ["OPENAI_API_KEY"])
+            ? undefined
+            : {
+                credential: "OPENAI_API_KEY",
+                modelExample: "openai/gpt-4o",
+                description: "an OpenAI API key",
+            };
+    }
+    if (normalizedModelId.startsWith("anthropic/")) {
+        return getConfiguredKey(environment, ["ANTHROPIC_API_KEY"])
+            ? undefined
+            : {
+                credential: "ANTHROPIC_API_KEY",
+                modelExample: "anthropic/claude-sonnet-4-5",
+                description: "an Anthropic API key",
+            };
+    }
+    if (normalizedModelId.startsWith("google/") ||
+        normalizedModelId.startsWith("gemini")) {
+        if (getConfiguredKey(environment, [
+            "GOOGLE_GENERATIVE_AI_API_KEY",
+            "GEMINI_API_KEY",
+        ])) {
+            return undefined;
+        }
+        return {
+            credential: "GOOGLE_GENERATIVE_AI_API_KEY",
+            modelExample: "google/gemini-2.5-pro",
+            description: "a Google AI API key",
+        };
+    }
+    if (normalizedModelId.includes("/")) {
+        return getConfiguredKey(environment, ["OPENROUTER_API_KEY"])
+            ? undefined
+            : {
+                credential: "OPENROUTER_API_KEY",
+                modelExample: normalizedModelId,
+                description: "an OpenRouter API key",
+            };
+    }
+    if (normalizedModelId.startsWith("claude")) {
+        if (getConfiguredKey(environment, [
+            "ANTHROPIC_API_KEY",
+            "OPENROUTER_API_KEY",
+        ])) {
+            return undefined;
+        }
+        return {
+            credential: "ANTHROPIC_API_KEY",
+            modelExample: "anthropic/claude-sonnet-4-5",
+            description: "an Anthropic API key",
+        };
+    }
+    if (normalizedModelId.startsWith("gpt") ||
+        normalizedModelId.startsWith("o1") ||
+        normalizedModelId.startsWith("o3")) {
+        if (getConfiguredKey(environment, ["OPENAI_API_KEY", "OPENROUTER_API_KEY"])) {
+            return undefined;
+        }
+        return {
+            credential: "OPENAI_API_KEY",
+            modelExample: "openai/gpt-4o",
+            description: "an OpenAI API key",
+        };
+    }
+    return getConfiguredKey(environment, ["OPENAI_API_KEY", "OPENROUTER_API_KEY"])
+        ? undefined
+        : {
+            credential: "OPENROUTER_API_KEY",
+            modelExample: `openrouter/${normalizedModelId}`,
+            description: "an OpenRouter API key",
+        };
+};
+export const getMissingProviderSetup = (modelId, environment = process.env) => {
+    const requiredProvider = getRequiredProvider(modelId, environment);
+    if (!requiredProvider)
+        return undefined;
+    const { credential, description, modelExample } = requiredProvider;
+    return [
+        `Iris Agent cannot start model '${modelId}' because ${credential} is not configured.`,
+        "",
+        `Provide ${description} before starting the agent:`,
+        `  ${credential}=<your-api-key> npx @4onstudios/iris-agent@latest --acp --modelId ${modelId}`,
+        "",
+        "For VS Code ACP Client, add the key to the agent's environment in settings.json:",
+        JSON.stringify({
+            "acp.agents": {
+                "Iris Agent": {
+                    command: "npx",
+                    args: ["@4onstudios/iris-agent@latest", "--acp", "--modelId", modelId],
+                    env: { [credential]: "<your-api-key>" },
+                },
+            },
+        }, null, 2),
+        "",
+        "Supported provider options:",
+        "  OpenRouter: OPENROUTER_API_KEY with --modelId openrouter/openai/gpt-4o",
+        "  OpenAI: OPENAI_API_KEY with --modelId openai/gpt-4o",
+        "  Anthropic: ANTHROPIC_API_KEY with --modelId anthropic/claude-sonnet-4-5",
+        "  Google: GOOGLE_GENERATIVE_AI_API_KEY with --modelId google/gemini-2.5-pro",
+        "  Hugging Face: HF_TOKEN with --modelId huggingface/Qwen/Qwen2.5-Coder-32B-Instruct",
+        "  Local Ollama: no cloud key; use --modelId ollama/<model> (optionally set OLLAMA_BASE_URL).",
+        `Example selected-model identifier: ${modelExample}`,
+    ].join("\n");
+};

package/dist/api/agent.js

@@ -465,7 +465,7 @@ const createGeneratedAgentRuntimeAdapter = (agent) => {
         descriptor: {
             id: "generated-agent-runtime",
             name: "Generated Agent Runtime",
-            version: "0.1.0",
+            version: "0.2.0",
             source: "external",
         },
         async startSession(context) {

package/dist/api/core/agent/tools/listDirectory.d.ts

@@ -51,13 +51,13 @@ export declare const listDirectoryTool: {
         includeHidden: z.ZodDefault<z.ZodBoolean>;
         maxDepth: z.ZodDefault<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
-        maxDepth?: number;
         recursive?: boolean;
+        maxDepth?: number;
         dirPath?: string;
         includeHidden?: boolean;
     }, {
-        maxDepth?: number;
         recursive?: boolean;
+        maxDepth?: number;
         dirPath?: string;
         includeHidden?: boolean;
     }>;

package/dist/cli.d.ts

@@ -2,7 +2,7 @@
 /**
  * iris-agent CLI with ACP (Agent Client Protocol) support
  * Usage:
- *   iris-agent --workspace /path/to/workspace --modelId openrouter/openai/gpt-4o --acp
+ *   iris-agent --acp
  *   iris-agent --workspace /path/to/workspace --modelId openrouter/openai/gpt-4o --chat
  */
 export {};

package/dist/cli.js

@@ -2,13 +2,14 @@
 /**
  * iris-agent CLI with ACP (Agent Client Protocol) support
  * Usage:
- *   iris-agent --workspace /path/to/workspace --modelId openrouter/openai/gpt-4o --acp
+ *   iris-agent --acp
  *   iris-agent --workspace /path/to/workspace --modelId openrouter/openai/gpt-4o --chat
  */
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { createCodingAgent } from "./api/core/agent/index.js";
 import { startAcpServer } from "./api/acp/acpServer.js";
+import { getMissingProviderSetup } from "./api/acp/providerSetup.js";
 const defaultModelId = process.env.MODEL_ID ||
     process.env.OPENROUTER_MODEL ||
     "openrouter/openai/gpt-4o";
@@ -17,7 +18,7 @@ const argv = yargs(hideBin(process.argv))
     alias: "w",
     type: "string",
     description: "Workspace root path",
-    required: true,
+    default: process.cwd(),
 })
     .option("acp", {
     alias: "a",
@@ -58,6 +59,12 @@ async function main() {
     console.log(`📁 Workspace: ${workspaceRoot}`);
     console.log(`🤖 Model: ${modelId}`);
     if (argv.acp) {
+        const missingProviderSetup = getMissingProviderSetup(modelId);
+        if (missingProviderSetup) {
+            console.error(missingProviderSetup);
+            process.exitCode = 1;
+            return;
+        }
         console.log("🔗 Starting ACP server over stdio...");
         await startAcpServer((requestedModelId, targetWorkspace) => createCodingAgent(requestedModelId || modelId, targetWorkspace || workspaceRoot), workspaceRoot);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4onstudios/iris-agent",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "private": false,
   "description": "Standalone HTTP coding-agent service and CLI with ACP (Agent Client Protocol) support.",
   "type": "module",