@gitterm/bot 0.1.0 → 0.2.0

package/dist/bot.d.ts

@@ -3,4 +3,4 @@ import type { Bot, BotOptions } from "./types.js";
  * A chat bot backed by GitTerm sandboxes: one sandbox per repository that pauses when idle and
  * wakes on the next message, and one OpenCode session per chat thread.
  */
-export declare function createBot(options: BotOptions): Bot;
+export declare function createBot(initial: BotOptions): Bot;

package/dist/index.js

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import { resolve as resolvePath } from "node:path";
 import {
   AgentRunError,
-  createGittermClient,
+  createGittermClient as createGittermClient2,
   GittermError as GittermError2,
   WorkspaceLifecycleError
 } from "@gitterm/sdk";
@@ -140,7 +140,7 @@ function modelsFor(model, saved) {
 async function githubFor(gitterm, repo) {
   return gitterm.integrations.connections.resolve(["github"], { repo: repo.url }).then(() => ["github"], () => []);
 }
-var RESUME_TIMEOUT_MS = 5 * 60000;
+var RESUME_TIMEOUT_MS = 4 * 60000;
 var SHARED_SPACE = "shared";
 var spaceOf = (message, shareChannels = false) => `${message.tenant ?? "installation"}:${message.direct ? `dm:${message.thread.channel}` : shareChannels ? SHARED_SPACE : `channel:${message.thread.channel}`}`;
 function createWorkspaceManager(input) {
@@ -306,6 +306,260 @@ ${SETUP_HINT}`);
   }
 }
 
+// src/saved.ts
+import {
+  createGittermClient
+} from "@gitterm/sdk";
+
+// src/env.ts
+import { existsSync, readFileSync } from "node:fs";
+import { parseArgs, parseEnv } from "node:util";
+var read = (env, name) => env[name]?.trim() || undefined;
+function positive(env, name) {
+  const value = read(env, name);
+  if (!value)
+    return;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0)
+    throw new Error(`${name} must be a positive integer`);
+  return parsed;
+}
+function parseChannels(value) {
+  const channels = {};
+  for (const entry of value.split(",")) {
+    const [channel, repo] = entry.split("=", 2).map((part) => part.trim());
+    if (!channel || !repo) {
+      throw new Error(`GITTERM_BOT_CHANNELS entries look like <channel id>=<repository url>`);
+    }
+    channels[channel] = repo;
+  }
+  return channels;
+}
+var list = (value) => value.split(",").map((entry) => entry.trim()).filter(Boolean);
+function readSandboxEnv(path) {
+  if (!path)
+    return;
+  try {
+    const parsed = parseEnv(readFileSync(path, "utf8"));
+    return Object.fromEntries(Object.entries(parsed).filter((entry) => entry[1] !== undefined));
+  } catch (error) {
+    throw new Error(`Could not read the sandbox environment file ${path}`, { cause: error });
+  }
+}
+function readInstructionsFile(path) {
+  if (!path)
+    return;
+  try {
+    return readFileSync(path, "utf8").trim() || undefined;
+  } catch (error) {
+    throw new Error(`Could not read the instructions file ${path}`, { cause: error });
+  }
+}
+function botOptionsFromEnv(env = process.env) {
+  const connections = read(env, "GITTERM_BOT_CONNECTIONS");
+  const provider = read(env, "GITTERM_BOT_PROVIDER");
+  const channels = read(env, "GITTERM_BOT_CHANNELS");
+  const options = {};
+  const botId = read(env, "GITTERM_BOT_ID");
+  if (botId)
+    options.botId = botId;
+  const allowedChannels = read(env, "GITTERM_BOT_ALLOWED_CHANNELS");
+  if (allowedChannels)
+    options.allowedChannels = list(allowedChannels);
+  const approvers = read(env, "GITTERM_BOT_APPROVERS");
+  if (approvers)
+    options.approvers = list(approvers);
+  if (read(env, "GITTERM_BOT_ALLOW_ALWAYS") === "true")
+    options.allowAlways = true;
+  if (read(env, "GITTERM_BOT_SHARE_CHANNELS") === "true")
+    options.shareChannels = true;
+  const maxPendingRequests = positive(env, "GITTERM_BOT_MAX_PENDING");
+  if (maxPendingRequests)
+    options.maxPendingRequests = maxPendingRequests;
+  const maxPendingPerUser = positive(env, "GITTERM_BOT_MAX_PENDING_PER_USER");
+  if (maxPendingPerUser)
+    options.maxPendingPerUser = maxPendingPerUser;
+  const repo = read(env, "GITTERM_BOT_REPO");
+  if (repo)
+    options.repo = repo;
+  if (channels)
+    options.channels = parseChannels(channels);
+  if (connections)
+    options.connections = list(connections);
+  const repos = read(env, "GITTERM_BOT_REPOS");
+  if (repos)
+    options.repos = list(repos);
+  const allowedUsers = read(env, "GITTERM_BOT_ALLOWED_USERS");
+  if (allowedUsers)
+    options.allowedUsers = list(allowedUsers);
+  if (read(env, "GITTERM_BOT_ALLOW_GUESTS") === "true")
+    options.allowGuests = true;
+  const setup = read(env, "GITTERM_BOT_SETUP");
+  if (setup)
+    options.setup = [setup];
+  const sandboxEnv = readSandboxEnv(read(env, "GITTERM_BOT_SANDBOX_ENV_FILE"));
+  if (sandboxEnv)
+    options.env = sandboxEnv;
+  const model = read(env, "GITTERM_BOT_MODEL");
+  const credential = read(env, "GITTERM_BOT_MODEL_CREDENTIAL");
+  const apiKey = read(env, "GITTERM_BOT_MODEL_API_KEY");
+  if ((credential || apiKey) && !model) {
+    throw new Error("GITTERM_BOT_MODEL_CREDENTIAL and GITTERM_BOT_MODEL_API_KEY need GITTERM_BOT_MODEL");
+  }
+  if (model) {
+    options.model = {
+      id: model,
+      ...credential ? { credential } : {},
+      ...apiKey ? { apiKey } : {}
+    };
+  }
+  const instructions = [
+    read(env, "GITTERM_BOT_INSTRUCTIONS"),
+    readInstructionsFile(read(env, "GITTERM_BOT_INSTRUCTIONS_FILE"))
+  ].filter(Boolean).join(`
+
+`);
+  if (instructions)
+    options.instructions = instructions;
+  const githubToken = read(env, "GITTERM_BOT_GITHUB_TOKEN");
+  if (provider || githubToken) {
+    options.workspace = {
+      ...provider ? { provider: { type: provider } } : {},
+      ...githubToken ? { repositoryCredentials: { token: githubToken } } : {}
+    };
+  }
+  const stateFile = read(env, "GITTERM_BOT_STATE_FILE");
+  if (stateFile)
+    options.stateFile = stateFile;
+  const runTimeoutMinutes = positive(env, "GITTERM_BOT_RUN_TIMEOUT_MINUTES");
+  if (runTimeoutMinutes)
+    options.runTimeoutMs = runTimeoutMinutes * 60000;
+  return options;
+}
+function cliOptions(argv = process.argv.slice(2)) {
+  if (existsSync(".env") && typeof process.loadEnvFile === "function")
+    process.loadEnvFile(".env");
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      repo: { type: "string" },
+      model: { type: "string" },
+      "instructions-file": { type: "string" },
+      help: { type: "boolean", short: "h" }
+    }
+  });
+  const flags = {
+    GITTERM_BOT_REPO: values.repo,
+    GITTERM_BOT_MODEL: values.model,
+    GITTERM_BOT_INSTRUCTIONS_FILE: values["instructions-file"]
+  };
+  const env = { ...process.env };
+  for (const [name, value] of Object.entries(flags))
+    if (value)
+      env[name] = value;
+  return { command: values.help ? "help" : positionals[0], options: botOptionsFromEnv(env) };
+}
+var BOT_ENV_HELP = `  Saved policy loads at startup; local settings cannot broaden its users, guests, or channels.
+
+  GITTERM_API_TOKEN               The bot's GitTerm token (dashboard → Bots creates one)
+  GITTERM_SERVER_URL              Self-hosted GitTerm API URL (default: hosted)
+  GITTERM_BOT_REPO                Repository for every channel: https://github.com/acme/app[#branch]
+  GITTERM_BOT_REPOS               More repositories people can name in a thread: url,url
+  GITTERM_BOT_CHANNELS            Per-channel repositories: <channel id>=<url>,…
+  GITTERM_BOT_MODEL               provider/model, e.g. anthropic/claude-sonnet-5-5
+  GITTERM_BOT_MODEL_CREDENTIAL    Saved credential label (default: the provider's default)
+  GITTERM_BOT_MODEL_API_KEY       Or a model API key for this bot only
+  GITTERM_BOT_GITHUB_TOKEN        Your own GitHub token instead of a GitTerm GitHub connection
+  GITTERM_BOT_CONNECTIONS         Tools besides GitHub, by name: Linear,Sentry
+  GITTERM_BOT_ALLOWED_USERS       Only these user ids may use the bot: U012,U034
+  GITTERM_BOT_ID                  Names an unsaved bot's sandboxes (saved bots use their own id)
+  GITTERM_BOT_ALLOWED_CHANNELS    Only these channel ids, whatever the repository routing
+  GITTERM_BOT_APPROVERS           Permission approver ids (default: requester only)
+  GITTERM_BOT_ALLOW_ALWAYS        true enables persistent approvals (default: disabled)
+  GITTERM_BOT_SHARE_CHANNELS      true opts equally trusted channels into a shared sandbox
+  GITTERM_BOT_MAX_PENDING[_PER_USER] Queue bounds (defaults: 20 total, 3 per user)
+  GITTERM_BOT_ALLOW_GUESTS        true lets guests and external people use the bot
+  GITTERM_BOT_INSTRUCTIONS[_FILE] What the agent should know and how to behave
+  GITTERM_BOT_SETUP               Command run before the agent starts, e.g. "pnpm install"
+  GITTERM_BOT_SANDBOX_ENV_FILE    dotenv file of variables for the sandbox (test credentials)
+  GITTERM_BOT_PROVIDER            Compute provider for new sandboxes (railway, e2b, …)
+  GITTERM_BOT_STATE_FILE, GITTERM_BOT_RUN_TIMEOUT_MINUTES`;
+var hasRepository = (options) => Boolean(options.repo || options.repos?.length || Object.keys(options.channels ?? {}).length);
+
+// src/saved.ts
+var isClient = (value) => typeof value === "object" && value !== null && ("runs" in value);
+async function withSavedConfig(options, platform, log = console) {
+  const gitterm = isClient(options.gitterm) ? options.gitterm : createGittermClient(options.gitterm);
+  const base = { ...options, gitterm };
+  const saved = await gitterm.bots.self();
+  if (!saved)
+    return base;
+  if (saved.platform !== platform) {
+    throw new Error(`This GitTerm token belongs to the ${saved.platform} bot "${saved.name}"; run that bot with it`);
+  }
+  log.info(`Using the settings saved for "${saved.name}" in GitTerm.`);
+  return { ...applySavedConfig(base, saved, log), localOptions: base };
+}
+function applySavedConfig(options, saved, log = console) {
+  const merged = { ...options };
+  const localRepos = [
+    options.repo,
+    ...options.repos ?? [],
+    ...Object.values(options.channels ?? {})
+  ].filter((repo) => repo !== undefined);
+  if (localRepos.some((repo) => repoKey(parseRepo(repo)) !== repoKey(parseRepo(saved.repo)))) {
+    throw new Error("Local repository routing exceeds the saved bot policy. Change its repository in GitTerm first.");
+  }
+  const localModel = typeof options.model === "string" ? options.model : options.model?.id;
+  if (localModel && localModel !== saved.model)
+    throw new Error("Local model exceeds the saved bot policy. Change its model in GitTerm first.");
+  if (options.connections?.some((reference) => !saved.connections.includes(reference))) {
+    throw new Error("Local connections exceed the saved bot policy. Select them in GitTerm first.");
+  }
+  merged.botId = saved.id;
+  if (saved.channels.length) {
+    merged.allowedChannels = options.allowedChannels ? options.allowedChannels.filter((id) => saved.channels.includes(id)) : saved.channels;
+  }
+  if (!hasRepository(options)) {
+    if (saved.channels.length) {
+      merged.channels = Object.fromEntries(saved.channels.map((id) => [id, saved.repo]));
+    } else {
+      merged.repo = saved.repo;
+    }
+  }
+  merged.model ??= {
+    id: saved.model,
+    ...saved.credential ? { credential: saved.credential } : {}
+  };
+  merged.connections ??= saved.connections;
+  if (saved.provider && !options.workspace?.provider) {
+    merged.workspace = {
+      ...options.workspace,
+      provider: { type: saved.provider }
+    };
+  }
+  if (saved.allowedUsers.length) {
+    merged.allowedUsers = options.allowedUsers ? options.allowedUsers.filter((id) => saved.allowedUsers.includes(id)) : saved.allowedUsers;
+  }
+  merged.allowGuests = saved.allowGuests && (options.allowGuests ?? true);
+  if (saved.instructions)
+    merged.instructions ??= saved.instructions;
+  if (saved.setup)
+    merged.setup ??= [saved.setup];
+  if (saved.githubAccess === "token" && !merged.workspace?.repositoryCredentials) {
+    log.warn(`"${saved.name}" uses your own GitHub token, but GITTERM_BOT_GITHUB_TOKEN is not set. Public repositories still work.`);
+  }
+  log.info("Effective bot authorization", {
+    botId: saved.id,
+    source: "saved policy, intersected with local restrictions",
+    channels: merged.allowedChannels ?? "all invited channels",
+    users: merged.allowedUsers ?? "channel members",
+    allowGuests: merged.allowGuests
+  });
+  return merged;
+}
+
 // src/state.ts
 import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
@@ -393,12 +647,14 @@ async function openStatusLine(adapter, thread, messageId) {
     const ms = Date.now() - startedAt;
     return ms >= TICK_MS ? ` (${minutes(ms)} min)` : "";
   };
-  const render = () => {
+  let queue = Promise.resolve();
+  const send = (update) => queue = queue.then(update).catch(noop);
+  const render = () => send(() => {
     if (id)
-      return adapter.edit(thread, id, `${current.message}${elapsed()}`).catch(noop);
+      return adapter.edit(thread, id, `${current.message}${elapsed()}`);
     const text = current.indicator && `${current.indicator}${elapsed()}`;
-    return adapter.indicate?.(thread, text).catch(noop);
-  };
+    return adapter.indicate?.(thread, text);
+  });
   const timer = setInterval(() => {
     if (id || current.indicator)
       render();
@@ -418,18 +674,15 @@ async function openStatusLine(adapter, thread, messageId) {
     async finish(text) {
       end();
       if (id) {
-        await adapter.edit(thread, id, text).catch(noop);
+        await send(() => adapter.edit(thread, id, text));
         return;
       }
-      await adapter.indicate?.(thread, "").catch(noop);
+      await send(() => adapter.indicate?.(thread, ""));
       await adapter.post(thread, text).catch(noop);
     },
     async remove() {
       end();
-      if (id)
-        await adapter.remove(thread, id).catch(noop);
-      else
-        await adapter.indicate?.(thread, "").catch(noop);
+      await send(() => id ? adapter.remove(thread, id) : adapter.indicate?.(thread, ""));
     },
     stop: end
   };
@@ -466,7 +719,7 @@ var threadKeyOf = (thread) => `${thread.channel}:${thread.thread}`;
 var noop2 = () => {
   return;
 };
-var isClient = (value) => typeof value === "object" && value !== null && ("runs" in value);
+var isClient2 = (value) => typeof value === "object" && value !== null && ("runs" in value);
 function describeAnswer(answer) {
   if (answer.kind === "question")
     return answer.labels.join(", ");
@@ -511,25 +764,9 @@ function recentIds(limit) {
     return true;
   };
 }
-function createBot(options) {
-  const { adapter } = options;
-  const log = options.logger ?? console;
-  const gitterm = isClient(options.gitterm) ? options.gitterm : createGittermClient(options.gitterm);
-  const runTimeoutMs = options.runTimeoutMs ?? 60 * 60000;
-  const inputTimeoutMs = options.inputTimeoutMs ?? 30 * 60000;
-  for (const [name, value, maximum] of [
-    ["runTimeoutMs", runTimeoutMs, 24 * 60 * 60000],
-    ["inputTimeoutMs", inputTimeoutMs, 24 * 60 * 60000],
-    ["maxPendingRequests", options.maxPendingRequests ?? 20, 1000],
-    ["maxPendingPerUser", options.maxPendingPerUser ?? 3, 1000]
-  ]) {
-    if (!Number.isSafeInteger(value) || value <= 0 || value > maximum)
-      throw new Error(`${name} must be a positive integer no greater than ${maximum}`);
-  }
+function settingsFor(options) {
   const defaultRepo = options.repo ? parseRepo(options.repo) : undefined;
   const extraRepos = (options.repos ?? []).map(parseRepo);
-  const allowedUsers = options.allowedUsers ? new Set(options.allowedUsers) : undefined;
-  const model = typeof options.model === "string" ? { id: options.model } : options.model;
   const channelRepos = new Map(Object.entries(options.channels ?? {}).map(([channel, repo]) => [channel, parseRepo(repo)]));
   const knownRepos = [
     ...new Map([defaultRepo, ...channelRepos.values(), ...extraRepos].filter((repo) => Boolean(repo)).map((repo) => [repoKey(repo), repo])).values()
@@ -537,6 +774,32 @@ function createBot(options) {
   if (knownRepos.length === 0) {
     throw new Error("Give the bot a `repo`, `repos` to choose from, or a repository per channel.");
   }
+  return {
+    options,
+    defaultRepo,
+    extraRepos,
+    channelRepos,
+    knownRepos,
+    allowedUsers: options.allowedUsers ? new Set(options.allowedUsers) : undefined,
+    model: typeof options.model === "string" ? { id: options.model } : options.model
+  };
+}
+function createBot(initial) {
+  const { adapter } = initial;
+  const log = initial.logger ?? console;
+  const gitterm = isClient2(initial.gitterm) ? initial.gitterm : createGittermClient2(initial.gitterm);
+  const runTimeoutMs = initial.runTimeoutMs ?? 60 * 60000;
+  const inputTimeoutMs = initial.inputTimeoutMs ?? 30 * 60000;
+  for (const [name, value, maximum] of [
+    ["runTimeoutMs", runTimeoutMs, 24 * 60 * 60000],
+    ["inputTimeoutMs", inputTimeoutMs, 24 * 60 * 60000],
+    ["maxPendingRequests", initial.maxPendingRequests ?? 20, 1000],
+    ["maxPendingPerUser", initial.maxPendingPerUser ?? 3, 1000]
+  ]) {
+    if (!Number.isSafeInteger(value) || value <= 0 || value > maximum)
+      throw new Error(`${name} must be a positive integer no greater than ${maximum}`);
+  }
+  let { options, defaultRepo, extraRepos, channelRepos, knownRepos, allowedUsers, model } = settingsFor(initial);
   const lock = createLocks();
   const fresh = recentIds(RECENT_MESSAGES);
   const active = new Map;
@@ -550,6 +813,7 @@ function createBot(options) {
   let running = false;
   let leaseTimer;
   let leaseId;
+  let savedAt;
   const tasks = new Set;
   const trackTask = (task) => {
     tasks.add(task);
@@ -1093,6 +1357,59 @@ function createBot(options) {
       }
     }
   }
+  const workspaceManager = () => createWorkspaceManager({
+    gitterm,
+    platform: adapter.platform,
+    scope,
+    botId: options.botId,
+    directRetentionMs: options.directRetentionMs,
+    identityPolicy: {
+      allowedUsers: options.allowedUsers,
+      allowGuests: options.allowGuests,
+      allowedChannels: options.allowedChannels,
+      shareChannels: options.shareChannels
+    },
+    connections: options.connections ?? [],
+    env: options.env ?? {},
+    setup: options.setup ?? [],
+    model,
+    instructions: agentInstructions(adapter.displayName, options.instructions),
+    overrides: options.workspace,
+    log
+  });
+  async function reload() {
+    const local = options.localOptions;
+    if (!local)
+      return;
+    try {
+      const saved = await gitterm.bots.self();
+      if (!saved)
+        return;
+      savedAt = saved.updatedAt;
+      if (saved.platform !== adapter.platform) {
+        log.warn(`"${saved.name}" is now a ${saved.platform} bot; run it on that platform.`);
+        return;
+      }
+      const next = settingsFor({
+        ...applySavedConfig(local, saved, log),
+        adapter,
+        localOptions: local
+      });
+      await checkSetup({
+        gitterm,
+        repos: next.knownRepos,
+        connections: next.options.connections ?? [],
+        model: next.model,
+        overrides: next.options.workspace,
+        log
+      });
+      ({ options, defaultRepo, extraRepos, channelRepos, knownRepos, allowedUsers, model } = next);
+      workspaces = workspaceManager();
+      log.info(`Applied the settings saved for "${saved.name}". New sandboxes use them; reset replaces an existing one.`);
+    } catch (error) {
+      log.warn("Could not apply the newly saved settings; keeping the current ones. Save again in GitTerm to retry.", error);
+    }
+  }
   const bot = {
     async start() {
       if (running)
@@ -1106,6 +1423,7 @@ function createBot(options) {
           throw new Error("Load the saved configuration with withSavedConfig() before starting a saved bot");
         }
         if (savedIdentity) {
+          savedAt = savedIdentity.updatedAt;
           const id = randomUUID();
           await claimLease(id);
           leaseId = id;
@@ -1115,7 +1433,11 @@ function createBot(options) {
             if (renewing || shutdown.signal.aborted)
               return;
             renewing = true;
-            gitterm.bots.acquireLease(id).then(() => failures = 0).catch((error) => {
+            gitterm.bots.acquireLease(id).then(async (lease) => {
+              failures = 0;
+              if (lease.updatedAt && lease.updatedAt !== savedAt)
+                await reload();
+            }).catch((error) => {
               const lost = error instanceof GittermError2 && error.code === "CONFLICT";
               if (!lost && ++failures < 2)
                 return;
@@ -1154,26 +1476,7 @@ function createBot(options) {
           accepts: servesChannel
         });
         scope = started.scope;
-        workspaces = createWorkspaceManager({
-          gitterm,
-          platform: adapter.platform,
-          scope,
-          botId: options.botId,
-          directRetentionMs: options.directRetentionMs,
-          identityPolicy: {
-            allowedUsers: options.allowedUsers,
-            allowGuests: options.allowGuests,
-            allowedChannels: options.allowedChannels,
-            shareChannels: options.shareChannels
-          },
-          connections: options.connections ?? [],
-          env: options.env ?? {},
-          setup: options.setup ?? [],
-          model,
-          instructions: agentInstructions(adapter.displayName, options.instructions),
-          overrides: options.workspace,
-          log
-        });
+        workspaces = workspaceManager();
         await recover();
         markReady();
         log.info(`GitTerm ${adapter.displayName} bot is running for ${knownRepos.map(repoLabel).join(", ")}.`);
@@ -1236,256 +1539,6 @@ async function downloadImage(url, options) {
     reader.releaseLock();
   }
 }
-// src/saved.ts
-import {
-  createGittermClient as createGittermClient2
-} from "@gitterm/sdk";
-
-// src/env.ts
-import { existsSync, readFileSync } from "node:fs";
-import { parseArgs, parseEnv } from "node:util";
-var read = (env, name) => env[name]?.trim() || undefined;
-function positive(env, name) {
-  const value = read(env, name);
-  if (!value)
-    return;
-  const parsed = Number(value);
-  if (!Number.isInteger(parsed) || parsed <= 0)
-    throw new Error(`${name} must be a positive integer`);
-  return parsed;
-}
-function parseChannels(value) {
-  const channels = {};
-  for (const entry of value.split(",")) {
-    const [channel, repo] = entry.split("=", 2).map((part) => part.trim());
-    if (!channel || !repo) {
-      throw new Error(`GITTERM_BOT_CHANNELS entries look like <channel id>=<repository url>`);
-    }
-    channels[channel] = repo;
-  }
-  return channels;
-}
-var list = (value) => value.split(",").map((entry) => entry.trim()).filter(Boolean);
-function readSandboxEnv(path) {
-  if (!path)
-    return;
-  try {
-    const parsed = parseEnv(readFileSync(path, "utf8"));
-    return Object.fromEntries(Object.entries(parsed).filter((entry) => entry[1] !== undefined));
-  } catch (error) {
-    throw new Error(`Could not read the sandbox environment file ${path}`, { cause: error });
-  }
-}
-function readInstructionsFile(path) {
-  if (!path)
-    return;
-  try {
-    return readFileSync(path, "utf8").trim() || undefined;
-  } catch (error) {
-    throw new Error(`Could not read the instructions file ${path}`, { cause: error });
-  }
-}
-function botOptionsFromEnv(env = process.env) {
-  const connections = read(env, "GITTERM_BOT_CONNECTIONS");
-  const provider = read(env, "GITTERM_BOT_PROVIDER");
-  const channels = read(env, "GITTERM_BOT_CHANNELS");
-  const options = {};
-  const botId = read(env, "GITTERM_BOT_ID");
-  if (botId)
-    options.botId = botId;
-  const allowedChannels = read(env, "GITTERM_BOT_ALLOWED_CHANNELS");
-  if (allowedChannels)
-    options.allowedChannels = list(allowedChannels);
-  const approvers = read(env, "GITTERM_BOT_APPROVERS");
-  if (approvers)
-    options.approvers = list(approvers);
-  if (read(env, "GITTERM_BOT_ALLOW_ALWAYS") === "true")
-    options.allowAlways = true;
-  if (read(env, "GITTERM_BOT_SHARE_CHANNELS") === "true")
-    options.shareChannels = true;
-  const maxPendingRequests = positive(env, "GITTERM_BOT_MAX_PENDING");
-  if (maxPendingRequests)
-    options.maxPendingRequests = maxPendingRequests;
-  const maxPendingPerUser = positive(env, "GITTERM_BOT_MAX_PENDING_PER_USER");
-  if (maxPendingPerUser)
-    options.maxPendingPerUser = maxPendingPerUser;
-  const repo = read(env, "GITTERM_BOT_REPO");
-  if (repo)
-    options.repo = repo;
-  if (channels)
-    options.channels = parseChannels(channels);
-  if (connections)
-    options.connections = list(connections);
-  const repos = read(env, "GITTERM_BOT_REPOS");
-  if (repos)
-    options.repos = list(repos);
-  const allowedUsers = read(env, "GITTERM_BOT_ALLOWED_USERS");
-  if (allowedUsers)
-    options.allowedUsers = list(allowedUsers);
-  if (read(env, "GITTERM_BOT_ALLOW_GUESTS") === "true")
-    options.allowGuests = true;
-  const setup = read(env, "GITTERM_BOT_SETUP");
-  if (setup)
-    options.setup = [setup];
-  const sandboxEnv = readSandboxEnv(read(env, "GITTERM_BOT_SANDBOX_ENV_FILE"));
-  if (sandboxEnv)
-    options.env = sandboxEnv;
-  const model = read(env, "GITTERM_BOT_MODEL");
-  const credential = read(env, "GITTERM_BOT_MODEL_CREDENTIAL");
-  const apiKey = read(env, "GITTERM_BOT_MODEL_API_KEY");
-  if ((credential || apiKey) && !model) {
-    throw new Error("GITTERM_BOT_MODEL_CREDENTIAL and GITTERM_BOT_MODEL_API_KEY need GITTERM_BOT_MODEL");
-  }
-  if (model) {
-    options.model = {
-      id: model,
-      ...credential ? { credential } : {},
-      ...apiKey ? { apiKey } : {}
-    };
-  }
-  const instructions = [
-    read(env, "GITTERM_BOT_INSTRUCTIONS"),
-    readInstructionsFile(read(env, "GITTERM_BOT_INSTRUCTIONS_FILE"))
-  ].filter(Boolean).join(`
-
-`);
-  if (instructions)
-    options.instructions = instructions;
-  const githubToken = read(env, "GITTERM_BOT_GITHUB_TOKEN");
-  if (provider || githubToken) {
-    options.workspace = {
-      ...provider ? { provider: { type: provider } } : {},
-      ...githubToken ? { repositoryCredentials: { token: githubToken } } : {}
-    };
-  }
-  const stateFile = read(env, "GITTERM_BOT_STATE_FILE");
-  if (stateFile)
-    options.stateFile = stateFile;
-  const runTimeoutMinutes = positive(env, "GITTERM_BOT_RUN_TIMEOUT_MINUTES");
-  if (runTimeoutMinutes)
-    options.runTimeoutMs = runTimeoutMinutes * 60000;
-  return options;
-}
-function cliOptions(argv = process.argv.slice(2)) {
-  if (existsSync(".env") && typeof process.loadEnvFile === "function")
-    process.loadEnvFile(".env");
-  const { values, positionals } = parseArgs({
-    args: argv,
-    allowPositionals: true,
-    options: {
-      repo: { type: "string" },
-      model: { type: "string" },
-      "instructions-file": { type: "string" },
-      help: { type: "boolean", short: "h" }
-    }
-  });
-  const flags = {
-    GITTERM_BOT_REPO: values.repo,
-    GITTERM_BOT_MODEL: values.model,
-    GITTERM_BOT_INSTRUCTIONS_FILE: values["instructions-file"]
-  };
-  const env = { ...process.env };
-  for (const [name, value] of Object.entries(flags))
-    if (value)
-      env[name] = value;
-  return { command: values.help ? "help" : positionals[0], options: botOptionsFromEnv(env) };
-}
-var BOT_ENV_HELP = `  Saved policy loads at startup; local settings cannot broaden its users, guests, or channels.
-
-  GITTERM_API_TOKEN               The bot's GitTerm token (dashboard → Bots creates one)
-  GITTERM_SERVER_URL              Self-hosted GitTerm API URL (default: hosted)
-  GITTERM_BOT_REPO                Repository for every channel: https://github.com/acme/app[#branch]
-  GITTERM_BOT_REPOS               More repositories people can name in a thread: url,url
-  GITTERM_BOT_CHANNELS            Per-channel repositories: <channel id>=<url>,…
-  GITTERM_BOT_MODEL               provider/model, e.g. anthropic/claude-sonnet-5-5
-  GITTERM_BOT_MODEL_CREDENTIAL    Saved credential label (default: the provider's default)
-  GITTERM_BOT_MODEL_API_KEY       Or a model API key for this bot only
-  GITTERM_BOT_GITHUB_TOKEN        Your own GitHub token instead of a GitTerm GitHub connection
-  GITTERM_BOT_CONNECTIONS         Tools besides GitHub, by name: Linear,Sentry
-  GITTERM_BOT_ALLOWED_USERS       Only these user ids may use the bot: U012,U034
-  GITTERM_BOT_ID                  Names an unsaved bot's sandboxes (saved bots use their own id)
-  GITTERM_BOT_ALLOWED_CHANNELS    Only these channel ids, whatever the repository routing
-  GITTERM_BOT_APPROVERS           Permission approver ids (default: requester only)
-  GITTERM_BOT_ALLOW_ALWAYS        true enables persistent approvals (default: disabled)
-  GITTERM_BOT_SHARE_CHANNELS      true opts equally trusted channels into a shared sandbox
-  GITTERM_BOT_MAX_PENDING[_PER_USER] Queue bounds (defaults: 20 total, 3 per user)
-  GITTERM_BOT_ALLOW_GUESTS        true lets guests and external people use the bot
-  GITTERM_BOT_INSTRUCTIONS[_FILE] What the agent should know and how to behave
-  GITTERM_BOT_SETUP               Command run before the agent starts, e.g. "pnpm install"
-  GITTERM_BOT_SANDBOX_ENV_FILE    dotenv file of variables for the sandbox (test credentials)
-  GITTERM_BOT_PROVIDER            Compute provider for new sandboxes (railway, e2b, …)
-  GITTERM_BOT_STATE_FILE, GITTERM_BOT_RUN_TIMEOUT_MINUTES`;
-var hasRepository = (options) => Boolean(options.repo || options.repos?.length || Object.keys(options.channels ?? {}).length);
-
-// src/saved.ts
-var isClient2 = (value) => typeof value === "object" && value !== null && ("runs" in value);
-async function withSavedConfig(options, platform, log = console) {
-  const gitterm = isClient2(options.gitterm) ? options.gitterm : createGittermClient2(options.gitterm);
-  const base = { ...options, gitterm };
-  const saved = await gitterm.bots.self();
-  if (!saved)
-    return base;
-  if (saved.platform !== platform) {
-    throw new Error(`This GitTerm token belongs to the ${saved.platform} bot "${saved.name}"; run that bot with it`);
-  }
-  const merged = { ...base };
-  const localRepos = [
-    options.repo,
-    ...options.repos ?? [],
-    ...Object.values(options.channels ?? {})
-  ].filter((repo) => repo !== undefined);
-  if (localRepos.some((repo) => repoKey(parseRepo(repo)) !== repoKey(parseRepo(saved.repo)))) {
-    throw new Error("Local repository routing exceeds the saved bot policy. Change its repository in GitTerm first.");
-  }
-  const localModel = typeof options.model === "string" ? options.model : options.model?.id;
-  if (localModel && localModel !== saved.model)
-    throw new Error("Local model exceeds the saved bot policy. Change its model in GitTerm first.");
-  if (options.connections?.some((reference) => !saved.connections.includes(reference))) {
-    throw new Error("Local connections exceed the saved bot policy. Select them in GitTerm first.");
-  }
-  merged.botId = saved.id;
-  if (saved.channels.length) {
-    merged.allowedChannels = options.allowedChannels ? options.allowedChannels.filter((id) => saved.channels.includes(id)) : saved.channels;
-  }
-  if (!hasRepository(options)) {
-    if (saved.channels.length) {
-      merged.channels = Object.fromEntries(saved.channels.map((id) => [id, saved.repo]));
-    } else {
-      merged.repo = saved.repo;
-    }
-  }
-  merged.model ??= {
-    id: saved.model,
-    ...saved.credential ? { credential: saved.credential } : {}
-  };
-  merged.connections ??= saved.connections;
-  if (saved.provider && !options.workspace?.provider) {
-    merged.workspace = {
-      ...options.workspace,
-      provider: { type: saved.provider }
-    };
-  }
-  if (saved.allowedUsers.length) {
-    merged.allowedUsers = options.allowedUsers ? options.allowedUsers.filter((id) => saved.allowedUsers.includes(id)) : saved.allowedUsers;
-  }
-  merged.allowGuests = saved.allowGuests && (options.allowGuests ?? true);
-  if (saved.instructions)
-    merged.instructions ??= saved.instructions;
-  if (saved.setup)
-    merged.setup ??= [saved.setup];
-  if (saved.githubAccess === "token" && !merged.workspace?.repositoryCredentials) {
-    log.warn(`"${saved.name}" uses your own GitHub token, but GITTERM_BOT_GITHUB_TOKEN is not set. Public repositories still work.`);
-  }
-  log.info(`Using the settings saved for "${saved.name}" in GitTerm.`);
-  log.info("Effective bot authorization", {
-    botId: saved.id,
-    source: "saved policy, intersected with local restrictions",
-    channels: merged.allowedChannels ?? "all invited channels",
-    users: merged.allowedUsers ?? "channel members",
-    allowGuests: merged.allowGuests
-  });
-  return merged;
-}
 // src/markdown.ts
 var TABLE_SEPARATOR = /^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|?\s*$/;
 function renderTable(lines) {

package/dist/saved.d.ts

@@ -4,7 +4,10 @@ type Options = Omit<BotOptions, "adapter">;
 /**
  * Adds the settings saved for this bot in the GitTerm dashboard (Bots), found by its API token.
  * Routing can be overridden locally; saved authorization is an upper bound. Without saved settings,
- * for example a token that isn't a bot's, the options come back unchanged.
+ * for example a token that isn't a bot's, the options come back unchanged. The options given are
+ * kept as `localOptions`, so the running bot can apply settings saved later the same way.
  */
 export declare function withSavedConfig(options: Options, platform: SavedBot["platform"], log?: BotLogger): Promise<Options>;
+/** Saved settings on top of local options; throws when the local options exceed them. */
+export declare function applySavedConfig(options: Options, saved: SavedBot, log?: BotLogger): Options;
 export {};

package/dist/types.d.ts

@@ -208,6 +208,11 @@ export type BotOptions = {
     /** How long a question or permission prompt waits for an answer. Default 30 min. */
     inputTimeoutMs?: number;
     logger?: BotLogger;
+    /**
+     * Set by `withSavedConfig`: the options before saved settings were added. A running bot applies
+     * settings saved later in the dashboard to these, without a restart.
+     */
+    localOptions?: Omit<BotOptions, "adapter" | "localOptions">;
 };
 export type Bot = {
     start(): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitterm/bot",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Chat-platform-agnostic engine for GitTerm agent bots: one sandbox per repository, one agent session per thread",
   "keywords": [
     "agent",
@@ -33,7 +33,7 @@
     "check-types": "tsc --noEmit"
   },
   "dependencies": {
-    "@gitterm/sdk": "^0.9.0"
+    "@gitterm/sdk": "^0.11.0"
   },
   "devDependencies": {
     "@types/bun": "^1.2.6",