@aion0/forge 0.9.16 → 0.9.19

package/lib/chat/tool-dispatcher.ts

@@ -48,8 +48,8 @@ const BUILTINS: Record<string, BuiltinHandler> = {
   // required (no default) vs optional (have default) so the agent can omit
   // optional ones rather than passing wrong placeholder values.
   trigger_pipeline: async (input) => {
-    const params = (input as { workflow?: string; input?: Record<string, unknown> } | undefined) || {};
-    const { listWorkflows, startPipeline, getPipeline } = await import('../pipeline');
+    const params = (input as { workflow?: string; input?: Record<string, unknown>; skills?: unknown } | undefined) || {};
+    const { listWorkflows, startPipeline, getPipeline, getWorkflow } = await import('../pipeline');
     if (!params.workflow) {
       const workflows = listWorkflows();
       if (workflows.length === 0) return 'No workflows found. Create one in <dataDir>/flows/.';
@@ -120,7 +120,48 @@ const BUILTINS: Record<string, BuiltinHandler> = {
     for (const [k, v] of Object.entries(params.input || {})) {
       stringInput[k] = v == null ? '' : typeof v === 'string' ? v : String(v);
     }
-    const pipeline = startPipeline(params.workflow, stringInput);
+
+    // Skills — same plumbing as Schedule / Job: pre-install each named
+    // skill into every project the workflow's nodes target, then thread
+    // the list through to startPipeline so per-task --append-system-prompt
+    // gets the /skill-name lines. Unknown skill names are warned (not
+    // blocked) — startPipeline ignores any that aren't installed by then.
+    let skills: string[] = [];
+    if (Array.isArray(params.skills)) {
+      skills = (params.skills as unknown[]).filter((s): s is string => typeof s === 'string' && s.trim() !== '');
+    }
+    if (skills.length > 0) {
+      try {
+        const { listSkills } = await import('../skills');
+        const known = new Set(listSkills().map((s: any) => s.name));
+        const unknown = skills.filter((s) => !known.has(s));
+        if (unknown.length > 0) {
+          return `Unknown skills: ${unknown.join(', ')}. Available: ${[...known].slice(0, 40).join(', ')}. Call list_forge_context to see all skills.`;
+        }
+        const { ensureInstalledInProject } = await import('../skills');
+        const { getProjectInfo } = await import('../projects');
+        const projectNames = new Set<string>();
+        for (const n of Object.values(wf.nodes || {})) {
+          if ((n as any).project) projectNames.add((n as any).project as string);
+        }
+        const seenPaths = new Set<string>();
+        for (const pName of projectNames) {
+          const resolved = pName.replace(/\{\{\s*input\.([\w-]+)\s*\}\}/g, (_, k: string) => stringInput[k] ?? '');
+          if (!resolved) continue;
+          const pInfo = getProjectInfo(resolved);
+          if (!pInfo || seenPaths.has(pInfo.path)) continue;
+          seenPaths.add(pInfo.path);
+          for (const skill of skills) {
+            try { await ensureInstalledInProject(skill, pInfo.path); }
+            catch (e) { console.warn(`[chat] skill "${skill}" install failed in ${pInfo.path}: ${(e as Error).message}`); }
+          }
+        }
+      } catch (e) {
+        console.warn(`[chat] skills preflight failed: ${(e as Error).message}`);
+      }
+    }
+
+    const pipeline = startPipeline(params.workflow, stringInput, { skills: skills.length ? skills : undefined });
     let line = `Pipeline started: ${pipeline.id} (workflow: ${params.workflow}, status: ${pipeline.status})`;
     if (pipeline.status === 'failed') {
       const fresh = getPipeline(pipeline.id) || pipeline;
@@ -242,6 +283,11 @@ export const BUILTIN_TOOL_DEFS: BuiltinToolDef[] = [
           type: 'object',
           description: 'Pipeline input fields as a flat object. Pass ONLY required fields (marked * in the list response) and optional fields the user explicitly named. Omit optional fields to use their defaults.',
         },
+        skills: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Forge skills (by name) to make available to every Claude task inside the pipeline — injected via --append-system-prompt. Pass when the user mentions skill names ("用 git-savvy", "with the code-reviewer skill"). Call list_forge_context to validate names. Omit if the user didn\'t mention any.',
+        },
       },
     },
   },
@@ -400,23 +446,54 @@ export async function dispatchTool(
   const protocol = located.tool.protocol || 'browser';
   const argInput = (call.input ?? {}) as Record<string, any>;
 
+  // Multi-instance overlay: when a connector's settings carry a
+  // `instances` array of `{name, ...}` objects, the tool's `instance`
+  // arg picks one and its fields are merged into the top-level settings
+  // namespace so templates like `{settings.base_url}` resolve against
+  // the chosen instance. Strictly guarded so connectors without this
+  // shape (the existing gitlab/mantis/teams/github-api/pmdb) are
+  // completely unaffected.
+  let effectiveSettings = located.settings;
+  let instances = (located.settings as any)?.instances;
+  // The `type: json` settings UI stores the field as a string literal,
+  // not a parsed value — accept both forms (string from the form,
+  // already-parsed array from manifests that ship a default).
+  if (typeof instances === 'string') {
+    try { instances = JSON.parse(instances); } catch { instances = null; }
+  }
+  if (
+    Array.isArray(instances) &&
+    instances.length > 0 &&
+    instances.every((i: any) => i && typeof i === 'object' && typeof i.name === 'string')
+  ) {
+    const wanted = typeof argInput.instance === 'string' ? argInput.instance : undefined;
+    const inst = wanted
+      ? instances.find((i: any) => i.name === wanted)
+      : instances[0];
+    if (wanted && !inst) {
+      const available = instances.map((i: any) => i.name).join(', ');
+      return { content: `unknown instance "${wanted}". Available: ${available}`, is_error: true };
+    }
+    effectiveSettings = { ...located.settings, ...inst };
+  }
+
   try {
     switch (protocol) {
       case 'http':
-        return await runHttp({ tool: located.tool, settings: located.settings, args: argInput, noTruncation: opts.noTruncation });
+        return await runHttp({ tool: located.tool, settings: effectiveSettings, args: argInput, connectorAuth: def.auth, noTruncation: opts.noTruncation });
       case 'shell':
-        return await runShell({ tool: located.tool, settings: located.settings, args: argInput });
+        return await runShell({ tool: located.tool, settings: effectiveSettings, args: argInput });
       case 'browser': {
         // Hand the whole connector + tool spec + input + settings to the
         // extension's runner.ts via the bridge. The extension keeps owning
         // the runner logic (tab acquire, navigate, executeScript).
-        const connector = buildConnectorPayload(def, located.entry, located.settings);
+        const connector = buildConnectorPayload(def, located.entry, effectiveSettings);
         const result = (await bridgeRpc('connector.run', {
           pluginId: located.connectorId,       // wire-name kept for extension
           toolName: located.toolName,
           input: argInput,
           connector,
-          settings: located.settings,
+          settings: effectiveSettings,
         })) as { content?: string; is_error?: boolean } | null;
         return { content: result?.content ?? '(no content returned)', is_error: !!result?.is_error };
       }

package/lib/chat-standalone.ts

@@ -144,6 +144,12 @@ async function handleSessionDelete(_req: IncomingMessage, res: ServerResponse, i
 }
 
 async function handleSessionClearMessages(_req: IncomingMessage, res: ServerResponse, id: string): Promise<void> {
+  // Intent: "Clear chat" only drops chat_messages rows. memory_store
+  // blocks (cursor / health / summary / facts) stay — once a fact has
+  // been extracted into long-term memory it should survive clearing
+  // the conversation it came from. Users can delete memory explicitly
+  // from the memory tab if they really want to forget. See
+  // forge-chat-memory-summarizer-design.md §11 decision 3.
   const session = getSession(id);
   if (!session) return sendJson(res, 404, { error: 'session not found' });
   const removed = clearSessionMessages(id);

package/lib/connectors/registry.ts

@@ -132,6 +132,70 @@ function getSecretFieldNames(def: ConnectorDefinition | null): string[] {
     .map(([name]) => name);
 }
 
+function getAllSettingsSchema(def: ConnectorDefinition | null): Record<string, ConnectorFieldSchema> {
+  const out: Record<string, ConnectorFieldSchema> = {};
+  if (!def) return out;
+  if (def.settings) Object.assign(out, def.settings);
+  for (const entry of def.connectors || []) {
+    if (entry.settings) Object.assign(out, entry.settings);
+  }
+  return out;
+}
+
+/**
+ * Walk a connector config value applying `op` (encrypt | decrypt) to
+ * every leaf whose schema is `type: 'secret'` or `'password'`. Recurses
+ * into `type: 'instances'` arrays so per-row sub-secrets (e.g. Jenkins
+ * api_token inside each instances row) get the same treatment as flat
+ * top-level secrets — otherwise nested credentials stay plaintext at
+ * rest. The on-disk shape is preserved: instances stay as a JSON-
+ * stringified array (which is how the type:instances UI persists it).
+ */
+function transformConnectorSecrets(
+  value: any,
+  schema: ConnectorFieldSchema | undefined,
+  op: 'encrypt' | 'decrypt',
+): any {
+  if (!schema) return value;
+  const t = String((schema as any)?.type || '');
+
+  if (t === 'secret' || t === 'password') {
+    if (typeof value !== 'string' || !value) return value;
+    if (op === 'encrypt') return isEncrypted(value) ? value : (() => {
+      try { return encryptSecret(value); } catch { return value; }
+    })();
+    if (op === 'decrypt') {
+      if (!isEncrypted(value)) return value;
+      try { return decryptSecret(value); }
+      catch { return value; }
+    }
+    return value;
+  }
+
+  if (t === 'instances' && (schema as any).fields) {
+    // Accept either the stored JSON-string form or an in-memory array.
+    let rows: any;
+    const wasString = typeof value === 'string';
+    if (wasString) {
+      try { rows = JSON.parse(value); } catch { return value; }
+    } else {
+      rows = value;
+    }
+    if (!Array.isArray(rows)) return value;
+    const transformed = rows.map((row: any) => {
+      if (!row || typeof row !== 'object') return row;
+      const out: any = { ...row };
+      for (const [k, sub] of Object.entries((schema as any).fields)) {
+        out[k] = transformConnectorSecrets(out[k], sub as ConnectorFieldSchema, op);
+      }
+      return out;
+    });
+    return wasString ? JSON.stringify(transformed) : transformed;
+  }
+
+  return value;
+}
+
 function loadStoreRaw(): ConfigStore {
   const p = configsFile();
   if (!existsSync(p)) return {};
@@ -144,20 +208,16 @@ function loadStoreRaw(): ConfigStore {
 
 function loadStore(): ConfigStore {
   const store = loadStoreRaw();
-  // Decrypt secret fields lazily — readers expect plaintext.
+  // Decrypt secret fields lazily — readers expect plaintext. Walks the
+  // schema so both flat top-level secrets AND nested instances sub-
+  // secrets get unwrapped uniformly.
   for (const [id, row] of Object.entries(store)) {
     if (!row?.config) continue;
     const def = getConnector(id);
-    const secrets = getSecretFieldNames(def);
-    if (!secrets.length) continue;
-    for (const key of secrets) {
-      const v = row.config[key];
-      if (typeof v === 'string' && isEncrypted(v)) {
-        try { row.config[key] = decryptSecret(v); }
-        catch (err) {
-          console.warn(`[connectors] failed to decrypt ${id}.${key}`, err);
-        }
-      }
+    const schema = getAllSettingsSchema(def);
+    for (const [k, sub] of Object.entries(schema)) {
+      try { row.config[k] = transformConnectorSecrets(row.config[k], sub, 'decrypt'); }
+      catch (err) { console.warn(`[connectors] failed to decrypt ${id}.${k}`, err); }
     }
   }
   return store;
@@ -169,15 +229,13 @@ function saveStore(store: ConfigStore): void {
   const out: ConfigStore = {};
   for (const [id, row] of Object.entries(store)) {
     const def = getConnector(id);
-    const secrets = new Set(getSecretFieldNames(def));
+    const schema = getAllSettingsSchema(def);
     const encryptedConfig: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(row.config || {})) {
-      if (secrets.has(k) && typeof v === 'string' && v.length > 0 && !isEncrypted(v)) {
-        try { encryptedConfig[k] = encryptSecret(v); }
-        catch { encryptedConfig[k] = v; }
-      } else {
-        encryptedConfig[k] = v;
-      }
+      const sub = schema[k];
+      encryptedConfig[k] = sub
+        ? transformConnectorSecrets(v, sub, 'encrypt')
+        : v;
     }
     out[id] = {
       config: encryptedConfig,

package/lib/connectors/types.ts

@@ -18,15 +18,55 @@ export type ConnectorProtocol = 'browser' | 'http' | 'shell';
 
 /** Schema for one settings or parameter field. */
 export interface ConnectorFieldSchema {
-  type: 'string' | 'number' | 'boolean' | 'secret' | 'json' | 'select';
+  type: 'string' | 'number' | 'boolean' | 'secret' | 'json' | 'select' | 'instances';
   label?: string;
   description?: string;
   required?: boolean;
   default?: unknown;
   /** select-type options */
   options?: string[];
+  /**
+   * For `type: 'instances'` — schema for each row's sub-fields. The UI
+   * renders one collapsible group per row, with these as inner inputs;
+   * one field MUST be named `name` and serves as the row label / the
+   * `instance` key referenced by tools. Stored on disk as a
+   * JSON-stringified array; the tool-dispatcher overlay parses it
+   * before template expansion.
+   */
+  fields?: Record<string, ConnectorFieldSchema>;
+  /**
+   * How this parameter's value is encoded when expanded into a URL path
+   * (`{args.X}` inside an HTTP tool's `request.url`). Default
+   * `uri_component` matches encodeURIComponent (slashes encoded). Use
+   * `none` when the value is a pre-formatted path that must stay literal
+   * (e.g. a Jenkins folder path `job/team/job/build`). `path_segments`
+   * encodes each `/`-separated segment individually but preserves the
+   * slashes (good for human-readable paths with spaces / unicode).
+   *
+   * Has no effect on values used in headers, query strings, or bodies —
+   * those go through token expansion without URL encoding either way.
+   */
+  url_encoding?: 'uri_component' | 'none' | 'path_segments';
 }
 
+/**
+ * How a connector authenticates its HTTP tools. Declared at the
+ * connector level (manifest top) and inherited by every `protocol: http`
+ * tool; an individual tool can override (`tool.auth: { type: none }`)
+ * to skip auth for a public endpoint.
+ *
+ * Forge resolves the scheme into the right header / query param at
+ * dispatch time so manifests don't have to hand-craft Authorization
+ * headers (and so secrets like `password` can be base64-encoded
+ * server-side without leaking to manifests).
+ */
+export type ConnectorAuth =
+  | { type: 'none' }
+  | { type: 'basic'; username: string; password: string }
+  | { type: 'bearer'; token: string }
+  | { type: 'header'; name: string; value: string }
+  | { type: 'query'; name: string; value: string };
+
 /**
  * Server-side HTTP request shape, used by `protocol: http` tools.
  * Template tokens {base_url}, {settings.*}, {args.*} are expanded at run time.
@@ -41,6 +81,36 @@ export interface HttpRequestSpec {
   query?: Record<string, string>;
   /** Body. string = sent as-is (templated); object = JSON.stringify'd (string values templated). */
   body?: string | Record<string, unknown>;
+  /**
+   * Alternative body form: when set, Forge serialises the referenced
+   * value as `application/x-www-form-urlencoded` (URLSearchParams). Use
+   * the literal placeholder string `{args.NAME}` to point at an object-
+   * valued parameter — typical for triggering Jenkins builds with a
+   * dynamic `params` map, or any old-school form-POST API. Ignored if
+   * `body` is also set.
+   */
+  body_form?: string | Record<string, unknown>;
+  /**
+   * Extra form-urlencoded keys merged into `body_form` server-side.
+   * Each value is a template (`{settings.gitlab_pat}` typical). Both
+   * the KEY and the VALUE are templated against settings. Keys with an
+   * empty / unsubstituted value are dropped (don't post blank
+   * secrets). The LLM never sees these — used to inject credentials a
+   * tool needs from settings without exposing them in the tool's
+   * declared parameters. Takes precedence over `body_form` if the
+   * same key appears in both.
+   */
+  body_form_inject?: Record<string, string>;
+  /**
+   * Name of a `type: instances` settings field whose every row is
+   * injected as one form-urlencoded key/value pair. Each row must have
+   * `name` (Jenkins build-param name) and `value` (the value to send).
+   * Server-side resolution — LLM never sees these. Empty rows are
+   * dropped. Use alongside or instead of `body_form_inject` when the
+   * user needs to configure arbitrary key/value pairs at runtime
+   * rather than baking them into the manifest.
+   */
+  body_form_inject_from?: string;
 }
 
 /**
@@ -102,6 +172,13 @@ export interface ConnectorTool {
 
   /** shell/http: timeout in milliseconds. Default 30000, max 300000. */
   timeout_ms?: number;
+
+  /**
+   * http: per-tool auth override. Falls back to the connector's
+   * top-level `auth` when omitted. Set `{ type: 'none' }` to skip
+   * auth on a public endpoint.
+   */
+  auth?: ConnectorAuth;
 }
 
 /**
@@ -230,6 +307,15 @@ export interface ConnectorDefinition {
   host_match?: string;
   login_redirect?: string;
 
+  /**
+   * Default HTTP auth scheme applied to every `protocol: http` tool
+   * in this connector. Tools can override via their own `auth` field.
+   * Omitting it = no auth applied by Forge (tools may still hand-craft
+   * an Authorization header in `request.headers`, like the v0.1 gitlab
+   * and github-api manifests).
+   */
+  auth?: ConnectorAuth;
+
   // ─── 1:N suite — list of sibling entries sharing auth ──
   connectors?: ConnectorEntry[];
 

package/lib/help-docs/21-build-connector.md

@@ -147,6 +147,145 @@ tools:
     timeout_ms: 15000
 ```
 
+#### Auth schemes
+
+Manifests can declare one auth scheme at the top and Forge applies it to every `protocol: http` tool — no need to hand-craft an `Authorization` header per tool, no manifest-side base64.
+
+```yaml
+# Connector-level (applies to all http tools).
+auth:
+  type: basic                       # basic | bearer | header | query | none
+  username: '{settings.username}'
+  password: '{settings.api_token}'
+
+# Variants:
+auth:
+  type: bearer
+  token: '{settings.token}'
+
+auth:
+  type: header
+  name: PRIVATE-TOKEN
+  value: '{settings.token}'
+
+auth:
+  type: query
+  name: access_token
+  value: '{settings.token}'
+```
+
+A tool can override (or disable) the inherited scheme with its own `auth:` block. `{ type: none }` skips auth entirely (public endpoint).
+
+#### Per-parameter URL encoding
+
+Default behaviour for an `{args.X}` in a URL path is `encodeURIComponent` — slashes become `%2F`. This is right for GitLab-style project paths but wrong for systems that expect literal slashes (Jenkins folder paths). Override per parameter:
+
+```yaml
+parameters:
+  job_path:
+    type: string
+    url_encoding: none              # uri_component (default) | none | path_segments
+    description: 'Pre-formatted Jenkins path with "job/" prefixes, e.g. "job/team-x/job/build".'
+  artifact_path:
+    type: string
+    url_encoding: path_segments     # encode each / segment individually, preserve slashes
+```
+
+#### Form-urlencoded bodies (`body_form`)
+
+For old-school form POST APIs (Jenkins `/buildWithParameters`, Slack `/chat.postMessage`, etc.). Point at a JSON-typed parameter and Forge serialises it with `URLSearchParams` (`application/x-www-form-urlencoded`):
+
+```yaml
+parameters:
+  params:
+    type: json
+    description: 'Flat object of build params: { "BRANCH": "main", "ENV": "stg" }'
+request:
+  method: POST
+  url: '{settings.base_url}/{args.job_path}/buildWithParameters'
+  body_form: '{args.params}'
+```
+
+LLMs sometimes JSON-stringify nested objects even when the schema says `type: json` — Forge automatically `JSON.parse`'s string-form values, so both shapes work.
+
+#### Server-side inject — credentials the LLM should never see
+
+Two forms.
+
+**1. `body_form_inject` (static keys, manifest-baked)** — useful when the manifest knows exactly which Jenkins / API param name the credential goes under.
+
+```yaml
+request:
+  body_form: '{args.params}'
+  body_form_inject:
+    GITLAB_PAT: '{settings.gitlab_pat}'         # key + value both templated against settings
+```
+
+Forge expands both the key and the value against settings (NOT args, so the LLM can't shadow). Empty / unsubstituted entries are dropped — optional secrets don't post blank values.
+
+**2. `body_form_inject_from` (dynamic, user-configured per instance)** — when each Jenkins job uses different param names, let the user supply a list of `{name, value}` rows in the settings UI; Forge injects every row.
+
+```yaml
+# settings declaration:
+settings:
+  inject_params:
+    type: instances                 # repeating-row UI
+    label: "Auto-inject build params"
+    fields:
+      name:  { type: string, required: true, label: "Param name" }
+      value: { type: secret, required: true, label: "Value" }
+
+# tool spec:
+request:
+  body_form: '{args.params}'
+  body_form_inject_from: 'inject_params'   # name of the instances settings field
+```
+
+User adds rows in the UI (e.g. `TOKEN_PASSWORD` → `<the-real-pat>`); Forge merges every row into the form body server-side. LLM passes only build-specific params, never sees the credentials.
+
+#### Multi-instance support (`settings.instances`)
+
+To let one install hit multiple servers of the same kind (prod + staging Jenkins, multiple GitLab tenants, etc.), declare your config under a `type: instances` field:
+
+```yaml
+settings:
+  instances:
+    type: instances
+    required: true
+    fields:
+      name:      { type: string, required: true }    # how the LLM picks one
+      base_url:  { type: string, required: true }
+      username:  { type: string, required: true }
+      api_token: { type: secret, required: true }
+```
+
+Each tool gains an implicit `instance` parameter (string). When the LLM passes `instance: "prod"`, Forge looks up the matching row from `settings.instances` and **overlays its fields onto the settings namespace** before template expansion — so your tool spec keeps using `{settings.base_url}` / `{settings.api_token}` as if they were flat. Omitting the arg defaults to the first row.
+
+Pair `instances` with `body_form_inject_from` for fully per-instance secret injection (each Jenkins instance has its own list of credentials to inject).
+
+Secrets nested inside an instance row (e.g. `api_token: { type: secret }` as a sub-field) are encrypted at rest by the same AES-256-GCM pipeline as flat top-level secrets; the UI masks them with bullets and the Settings → Connectors panel renders a "Replace" button to change them.
+
+#### Nested `instances` (rows of rows)
+
+A sub-field of an `instances` schema can itself be `type: instances`, and the renderer handles the nesting. This is how Jenkins's `inject_params` lives inside each instance row:
+
+```yaml
+settings:
+  instances:
+    type: instances
+    fields:
+      name:     { type: string, required: true }
+      base_url: { type: string, required: true }
+      api_token: { type: secret, required: true }
+      inject_params:               # nested instances inside a row
+        type: instances
+        fields:
+          name:  { type: string, required: true }
+          value: { type: secret, required: true }
+```
+
+UI: each top-level instance row expands to a form that includes a nested rows-list for its sub-collection. Encryption recurses, so per-row secrets in either level encrypt correctly.
+
 ### test block
 
 A connector can ship a self-test so the Settings → Connectors UI's

package/lib/init.ts

@@ -249,6 +249,7 @@ export function ensureInitialized() {
   startWorkspaceProcess(); // spawns workspace-standalone
   startBrowserBridgeProcess(); // spawns browser-bridge-standalone
   startChatProcess(); // spawns chat-standalone
+  startMemoryProcess(); // spawns memory-standalone
 
   const settings = loadSettings();
   if (settings.tunnelAutoStart) {
@@ -402,3 +403,18 @@ function startBrowserBridgeProcess() {
   });
   tester.listen(bridgePort);
 }
+
+let memoryChild: ReturnType<typeof spawn> | null = null;
+
+function startMemoryProcess() {
+  if (memoryChild) return;
+  // No HTTP port — pure background poller. Just spawn-if-not-running.
+  const script = join(process.cwd(), 'lib', 'memory-standalone.ts');
+  memoryChild = spawn('npx', ['tsx', script], {
+    stdio: ['ignore', 'inherit', 'inherit'],
+    env: { ...process.env },
+    detached: false,
+  });
+  memoryChild.on('exit', () => { memoryChild = null; });
+  console.log('[memory] Started standalone (pid:', memoryChild.pid, ')');
+}

package/lib/memory/compress-messages.ts

@@ -0,0 +1,65 @@
+/**
+ * Compact chat messages into a summarizer-friendly transcript.
+ *
+ * Raw tool_use / tool_result blocks can each carry kilobytes of JSON
+ * (stack traces, encoded args, HTML responses). Feeding those into the
+ * summarizer LLM wastes input tokens and crowds out actual dialogue.
+ *
+ * This module flattens each Message into one or more text lines:
+ *   - text blocks pass through (truncated to MAX_TEXT_CHARS)
+ *   - tool_use → `tool[name](key1, key2, …)`
+ *   - tool_result → `→ ok: <first line>` or `→ err: <first line>`
+ *
+ * Output is a plain string ready to drop into the summarizer prompt.
+ */
+
+import type { ContentBlock, Message, ToolResultBlock, ToolUseBlock } from '../chat/types';
+
+const MAX_TEXT_CHARS = 1200;
+const MAX_TOOL_RESULT_CHARS = 200;
+const MAX_INPUT_KEYS = 8;
+
+export function compressMessagesForSummarizer(messages: Message[]): string {
+  const lines: string[] = [];
+  for (const m of messages) {
+    for (const block of m.blocks) {
+      const rendered = renderBlock(m.role, block);
+      if (rendered) lines.push(rendered);
+    }
+  }
+  return lines.join('\n');
+}
+
+function renderBlock(role: 'user' | 'assistant', block: ContentBlock): string | null {
+  if (block.type === 'text') {
+    const text = truncate(block.text.trim(), MAX_TEXT_CHARS);
+    if (!text) return null;
+    return `${role}: ${text}`;
+  }
+  if (block.type === 'tool_use') {
+    return `${role}: ${renderToolUse(block)}`;
+  }
+  if (block.type === 'tool_result') {
+    return `${role}: ${renderToolResult(block)}`;
+  }
+  return null;
+}
+
+function renderToolUse(block: ToolUseBlock): string {
+  const keys = block.input && typeof block.input === 'object'
+    ? Object.keys(block.input as Record<string, unknown>).slice(0, MAX_INPUT_KEYS)
+    : [];
+  const argsStr = keys.length > 0 ? `(${keys.join(', ')})` : '()';
+  return `tool[${block.name}]${argsStr}`;
+}
+
+function renderToolResult(block: ToolResultBlock): string {
+  const firstLine = (block.content ?? '').split(/\r?\n/, 1)[0] ?? '';
+  const head = truncate(firstLine, MAX_TOOL_RESULT_CHARS);
+  return block.is_error ? `→ err: ${head}` : `→ ok: ${head}`;
+}
+
+function truncate(s: string, max: number): string {
+  if (s.length <= max) return s;
+  return s.slice(0, max) + '…';
+}