typeclaw 0.1.4 → 0.1.6

package/src/agent/index.ts

@@ -5,8 +5,11 @@ import { fileURLToPath } from 'node:url'
 import { createAgentSession, DefaultResourceLoader, SessionManager } from '@mariozechner/pi-coding-agent'
 import type { AgentSession, ToolDefinition } from '@mariozechner/pi-coding-agent'
 
+import { loadMemory } from '@/bundled-plugins/memory/load-memory'
 import type { ChannelRouter } from '@/channels/router'
-import { getConfig, resolveModel } from '@/config'
+import { getConfig, resolveModel, resolveProfile } from '@/config'
+import { providerForModelRef } from '@/config/providers'
+import type { PermissionService } from '@/permissions'
 import type {
   BuiltinToolRef,
   HookBus,
@@ -19,14 +22,21 @@ import { materializeSkills } from '@/plugin'
 import type { ReloadRegistry } from '@/reload'
 import type { Stream } from '@/stream'
 
-import { getAuth } from './auth'
+import { getAuthFor } from './auth'
 import { createCompactionSettingsManager } from './compaction'
 import { renderGitNudge } from './git-nudge'
+import { lookAtTool } from './multimodal'
 import { resolveBuiltinToolRefs, wrapPluginTool, wrapSystemAgentTool, wrapSystemTool } from './plugin-tools'
 import { createReloadTool } from './reload-tool'
 import { loadSelf } from './self'
-import { renderSessionOrigin, type SessionOrigin } from './session-origin'
+import { renderSessionOrigin, type SessionOrigin, type SessionRoleContext } from './session-origin'
 import { DEFAULT_SYSTEM_PROMPT } from './system-prompt'
+import {
+  createBudgetState,
+  type ToolResultBudget,
+  wrapAgentToolWithBudget,
+  wrapToolDefinitionWithBudget,
+} from './tool-result-budget'
 import { createChannelFetchAttachmentTool } from './tools/channel-fetch-attachment'
 import { createChannelHistoryTool } from './tools/channel-history'
 import { createChannelReplyTool } from './tools/channel-reply'
@@ -56,6 +66,15 @@ export type PluginSubagentSelection = {
   toolNamePrefix: string
 }
 
+// Mutable holder for the live session origin. Pass this when the origin
+// must be updated turn-by-turn after session creation (channel sessions
+// whose `lastInboundAuthorId` changes with each inbound message). Tool
+// wrappers read `.current` at execute time, not at wrap time, so the
+// `tool.before` event carries the per-turn actor identity rather than the
+// stale session-creation snapshot. Sessions that never mutate origin
+// (TUI, cron, subagent) can omit it and pass `origin` instead.
+export type SessionOriginRef = { current: SessionOrigin | undefined }
+
 export type CreateSessionOptions = {
   reloadRegistry?: ReloadRegistry
   sessionManager?: SessionManager
@@ -68,6 +87,13 @@ export type CreateSessionOptions = {
   // Rendered into the system prompt so the agent knows who's listening, where
   // its output goes, and what to pass to channel_send.
   origin?: SessionOrigin
+  // Live origin holder. When provided, the tool wrappers read this at execute
+  // time so `tool.before` events see the current-turn origin. Caller is
+  // responsible for keeping `.current` up to date. If both `origin` and
+  // `originRef` are passed, the ref wins for tool stamping; the static
+  // `origin` still drives the initial system-prompt rendering and channel
+  // tool addressing (those are only valid at session-creation time).
+  originRef?: SessionOriginRef
   tools?: AgentSessionTools
   customTools?: ToolDefinition[]
   plugins?: PluginSessionWiring
@@ -78,6 +104,41 @@ export type CreateSessionOptions = {
   // Enables the `restart` tool. Set when the agent is running inside a
   // typeclaw-managed container. Read from TYPECLAW_CONTAINER_NAME at the call site.
   containerName?: string
+  // The permission service the runtime resolved at boot. When provided, the
+  // resolved role and permission list for `options.origin` are rendered into
+  // the system prompt under `## Your role in this session`. The block is
+  // emitted for channel/cron/subagent sessions, and for TUI sessions only
+  // when the resolved role is not the built-in `owner` (because TUI
+  // resolving to `owner` is the common case and we save tokens on every
+  // interactive session). Omitting `permissions` falls back to the previous
+  // behavior (no role annotation), which is what tests and stand-alone
+  // callers want.
+  //
+  // The role rendered here is a session-creation snapshot. Channel sessions
+  // re-resolve per-turn through `originRef` for tool gating, but the system
+  // prompt is not regenerated; see `typeclaw-permissions` skill for how the
+  // agent should interpret the snapshot on later turns.
+  permissions?: PermissionService
+  // Model profile name. Resolved against `config.models` to pick the concrete
+  // model ref this session binds to. Unknown profile names fall back to
+  // `default` with a one-time console warning. Omitted → `default`. Threaded
+  // through from the caller (subagent declarations, future per-spawn tool
+  // overrides) so different sessions on the same agent can run different
+  // models without per-session config edits.
+  profile?: string
+  // Defensive ceiling on cumulative bytes of tool-result text per session,
+  // applied to the named tools only. See `src/agent/tool-result-budget.ts`
+  // for the rationale. Intended for subagents that read large files
+  // (memory-logger, dreaming); leaving this undefined disables the budget
+  // entirely, which is the right default for TUI / channel / plugin-tool
+  // sessions where the human (or hooks) bound tool-result size.
+  toolResultBudget?: ToolResultBudget
+  // Optional override for the message returned to the agent once
+  // `toolResultBudget` is exhausted. Subagents whose recovery path differs
+  // from the default ("advance the watermark from a recent id you have
+  // already seen") provide their own here. See `ToolResultBudget` for the
+  // shared shape.
+  toolResultBudgetMessage?: ToolResultBudget['exhaustedMessage']
 }
 
 export type CreateSessionResult = {
@@ -91,7 +152,11 @@ export async function createSession(options: CreateSessionOptions = {}): Promise
 }
 
 export async function createSessionWithDispose(options: CreateSessionOptions = {}): Promise<CreateSessionResult> {
-  const { authStorage, modelRegistry } = getAuth()
+  const resolved = resolveProfile(getConfig().models, options.profile)
+  if (resolved.fellBackToDefault && options.profile !== undefined && options.profile !== 'default') {
+    warnProfileFallbackOnce(options.profile, resolved.ref)
+  }
+  const { authStorage, modelRegistry } = getAuthFor(providerForModelRef(resolved.ref))
 
   const materializedSkills =
     options.plugins && options.plugins.registry.skills.length > 0
@@ -106,23 +171,46 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
 
   const resourceLoader =
     options.systemPromptOverride !== undefined
-      ? await createOverrideResourceLoader(options.systemPromptOverride, options.origin)
+      ? await createOverrideResourceLoader(options.systemPromptOverride, options.origin, options.permissions)
       : await createResourceLoader({
           ...(options.plugins ? { plugins: options.plugins, materializedSkills } : {}),
           ...(options.origin ? { origin: options.origin } : {}),
+          ...(options.permissions ? { permissions: options.permissions } : {}),
         })
 
+  const getOrigin: () => SessionOrigin | undefined =
+    options.originRef !== undefined ? () => options.originRef!.current : () => options.origin
+
   const subagentBuiltinTools = options.pluginSubagent?.toolRefs
     ? resolveBuiltinToolRefs(options.pluginSubagent.toolRefs)
     : undefined
   const pluginCustomTools = options.pluginSubagent
-    ? wrapSubagentCustomTools(options.pluginSubagent, options.plugins)
-    : wrapRegistryTools(options.plugins)
+    ? wrapSubagentCustomTools(options.pluginSubagent, options.plugins, getOrigin)
+    : wrapRegistryTools(options.plugins, getOrigin)
+
+  // Per-run budget state for the tool-result byte ceiling. Allocated once per
+  // session creation and threaded into every wrapped tool so they share the
+  // same counter. Only used when the session declares a budget; the wrappers
+  // pass non-listed tools through unchanged, so the counter stays at zero for
+  // sessions without a budget configured.
+  const sessionBudget: ToolResultBudget | undefined = options.toolResultBudget
+    ? options.toolResultBudgetMessage !== undefined
+      ? { ...options.toolResultBudget, exhaustedMessage: options.toolResultBudgetMessage }
+      : options.toolResultBudget
+    : undefined
+  const sessionBudgetState = sessionBudget ? createBudgetState() : undefined
 
-  const tools = wrapSystemAgentTools(
+  const hookWrappedTools = wrapSystemAgentTools(
     options.tools ?? (subagentBuiltinTools as AgentSessionTools | undefined),
     options.plugins,
+    getOrigin,
   )
+  const tools =
+    sessionBudget && sessionBudgetState && hookWrappedTools
+      ? (hookWrappedTools.map((t) =>
+          wrapAgentToolWithBudget(t, sessionBudget, sessionBudgetState),
+        ) as typeof hookWrappedTools)
+      : hookWrappedTools
 
   // Hoisted above tool construction so the restart tool can be wired with the
   // session's stable identity (sessionManager.getSessionId()). Subscribers use
@@ -138,6 +226,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
         : [
             websearchTool,
             webfetchTool,
+            lookAtTool,
             ...(options.reloadRegistry ? [createReloadTool({ registry: options.reloadRegistry })] : []),
             ...(options.stream ? [createStreamSnapshotTool({ stream: options.stream })] : []),
             ...buildChannelTools(options.channelRouter, options.origin),
@@ -151,9 +240,13 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
                 ]
               : []),
           ]
-  const customTools = [...wrapSystemTools(customSystemTools, options.plugins), ...pluginCustomTools]
+  const customToolsPreBudget = [...wrapSystemTools(customSystemTools, options.plugins, getOrigin), ...pluginCustomTools]
+  const customTools =
+    sessionBudget && sessionBudgetState
+      ? customToolsPreBudget.map((t) => wrapToolDefinitionWithBudget(t, sessionBudget, sessionBudgetState))
+      : customToolsPreBudget
 
-  const model = resolveModel(getConfig().model)
+  const model = resolveModel(resolved.ref)
   const { session } = await createAgentSession({
     model,
     sessionManager,
@@ -294,7 +387,10 @@ export function buildChannelTools(
   return tools
 }
 
-function wrapRegistryTools(plugins: PluginSessionWiring | undefined): ToolDefinition[] {
+function wrapRegistryTools(
+  plugins: PluginSessionWiring | undefined,
+  getOrigin: () => SessionOrigin | undefined,
+): ToolDefinition[] {
   if (!plugins) return []
   return plugins.registry.tools.map((t: PluginRegisteredTool) =>
     wrapPluginTool(t.tool, {
@@ -304,6 +400,7 @@ function wrapRegistryTools(plugins: PluginSessionWiring | undefined): ToolDefini
       sessionId: plugins.sessionId,
       logger: t.logger,
       hooks: plugins.hooks,
+      getOrigin,
     }),
   )
 }
@@ -311,6 +408,7 @@ function wrapRegistryTools(plugins: PluginSessionWiring | undefined): ToolDefini
 function wrapSystemAgentTools(
   tools: AgentSessionTools | undefined,
   plugins: PluginSessionWiring | undefined,
+  getOrigin: () => SessionOrigin | undefined,
 ): AgentSessionTools | undefined {
   if (!tools || !hasToolHooks(plugins)) return tools
   return tools.map((tool) =>
@@ -318,17 +416,23 @@ function wrapSystemAgentTools(
       agentDir: plugins.agentDir,
       sessionId: plugins.sessionId,
       hooks: plugins.hooks,
+      getOrigin,
     }),
   )
 }
 
-function wrapSystemTools(tools: ToolDefinition[], plugins: PluginSessionWiring | undefined): ToolDefinition[] {
+function wrapSystemTools(
+  tools: ToolDefinition[],
+  plugins: PluginSessionWiring | undefined,
+  getOrigin: () => SessionOrigin | undefined,
+): ToolDefinition[] {
   if (!hasToolHooks(plugins)) return tools
   return tools.map((tool) =>
     wrapSystemTool(tool, {
       agentDir: plugins.agentDir,
       sessionId: plugins.sessionId,
       hooks: plugins.hooks,
+      getOrigin,
     }),
   )
 }
@@ -341,6 +445,7 @@ function hasToolHooks(plugins: PluginSessionWiring | undefined): plugins is Plug
 function wrapSubagentCustomTools(
   selection: PluginSubagentSelection,
   plugins: PluginSessionWiring | undefined,
+  getOrigin: () => SessionOrigin | undefined,
 ): ToolDefinition[] {
   if (!selection.customTools || !plugins) return []
   const logger = makePluginLogger(selection.pluginName)
@@ -352,6 +457,7 @@ function wrapSubagentCustomTools(
       sessionId: plugins.sessionId,
       logger,
       hooks: plugins.hooks,
+      getOrigin,
     }),
   )
 }
@@ -368,9 +474,11 @@ function makePluginLogger(pluginName: string) {
 export async function createOverrideResourceLoader(
   systemPrompt: string,
   origin?: SessionOrigin,
+  permissions?: PermissionService,
 ): Promise<DefaultResourceLoader> {
+  const finalPrompt = withOrigin(systemPrompt, origin, permissions)
   const loader = new DefaultResourceLoader({
-    systemPromptOverride: () => withOrigin(systemPrompt, origin),
+    systemPromptOverride: () => finalPrompt,
     appendSystemPromptOverride: () => [],
   })
   await loader.reload()
@@ -382,6 +490,7 @@ export type CreateResourceLoaderOptions = {
   plugins?: PluginSessionWiring
   materializedSkills?: MaterializedSkills | null
   origin?: SessionOrigin
+  permissions?: PermissionService
 }
 
 export async function createResourceLoader(options: CreateResourceLoaderOptions = {}): Promise<DefaultResourceLoader> {
@@ -395,14 +504,32 @@ export async function createResourceLoader(options: CreateResourceLoaderOptions
     systemPrompt = event.prompt
   }
 
-  // Appended last so the dirty-files snapshot is the most-recent context the
-  // agent reads, and so its bytes sit in the cache-suffix region rather than
-  // splitting the cacheable prefix shared by clean-worktree sessions.
+  // Cache-suffix ordering: least-volatile sections first, most-volatile last.
+  // This minimises the number of cached prompt bytes invalidated when a
+  // section changes (the provider's prompt cache hits up to the first byte
+  // that differs).
+  //
+  // 1. origin block — stable across all sessions of the same kind.
+  // 2. gitNudge — rare changes; agent folders force-commit sessions/ and
+  //    memory/ after every turn, so the dirty-files list is empty most of
+  //    the time.
+  // 3. memorySection — most volatile: MEMORY.md grows on every dream cycle
+  //    and memory/yyyy-MM-dd.md grows after every channel turn that triggers
+  //    memory-logger. Pinning it to the end keeps everything above it
+  //    cacheable across session resurrections.
+  systemPrompt = withOrigin(systemPrompt, options.origin, options.permissions)
+
   const gitNudge = await renderGitNudge(agentDir)
   if (gitNudge !== '') {
     systemPrompt = `${systemPrompt}\n\n${gitNudge}`
   }
 
+  const memorySection = await loadMemory(agentDir, {
+    ...(options.origin !== undefined ? { origin: options.origin } : {}),
+    ...(options.plugins?.sessionId !== undefined ? { currentSessionId: options.plugins.sessionId } : {}),
+  })
+  systemPrompt = `${systemPrompt}\n\n${memorySection}`
+
   const additionalSkillPaths = [getBundledSkillsDir()]
   // pi-coding-agent's DefaultResourceLoader auto-discovers <agentDir>/skills/
   // but not <agentDir>/.agents/skills/. We do not scaffold <agentDir>/skills/
@@ -433,7 +560,7 @@ export async function createResourceLoader(options: CreateResourceLoaderOptions
   }
 
   const loader = new DefaultResourceLoader({
-    systemPromptOverride: () => withOrigin(systemPrompt, options.origin),
+    systemPromptOverride: () => systemPrompt,
     appendSystemPromptOverride: () => [],
     additionalSkillPaths,
   })
@@ -441,11 +568,54 @@ export async function createResourceLoader(options: CreateResourceLoaderOptions
   return loader
 }
 
-function withOrigin(systemPrompt: string, origin: SessionOrigin | undefined): string {
+function withOrigin(
+  systemPrompt: string,
+  origin: SessionOrigin | undefined,
+  permissions: PermissionService | undefined,
+): string {
   if (!origin) return systemPrompt
-  return `${systemPrompt}\n\n${renderSessionOrigin(origin)}`
+  const roleContext = resolveRoleContext(origin, permissions)
+  return `${systemPrompt}\n\n${renderSessionOrigin(origin, Date.now(), roleContext)}`
+}
+
+function resolveRoleContext(
+  origin: SessionOrigin,
+  permissions: PermissionService | undefined,
+): SessionRoleContext | undefined {
+  if (permissions === undefined) return undefined
+  const described = permissions.describe(origin)
+  // TUI normally resolves to `owner` via the built-in `owner.match = [tui]`
+  // entry, and we skip the role block in that case to save tokens on every
+  // interactive session. But user-declared roles can match TUI first (the
+  // resolver is first-match-wins in declaration order), so a non-owner TUI
+  // role is possible and the agent needs to see it. The "TUI is always owner"
+  // shorthand in docs is the common case, not an invariant.
+  if (origin.kind === 'tui' && described.role === 'owner') return undefined
+  return described
 }
 
 export function getBundledSkillsDir(): string {
   return join(dirname(fileURLToPath(import.meta.url)), '..', 'skills')
 }
+
+// Profile-fallback warning is fired once per (profile, ref) pair per process.
+// Without rate-limiting, every memory-logger spawn (~every idle event) would
+// emit a fresh warning when the user has only `default` configured — tens of
+// warnings per channel session is noise the operator will learn to ignore.
+// The pair includes `ref` so a config reload that changes `default` re-warns.
+const profileFallbackWarned = new Set<string>()
+
+function warnProfileFallbackOnce(profile: string, ref: string): void {
+  const key = `${profile}\x00${ref}`
+  if (profileFallbackWarned.has(key)) return
+  profileFallbackWarned.add(key)
+  console.warn(
+    `[agent] unknown model profile "${profile}"; falling back to "default" (${ref}). Add it under \`models\` in typeclaw.json to remove this warning. (further occurrences suppressed)`,
+  )
+}
+
+// Test-only: clear the rate-limit cache so a test can assert the warning fires
+// once after rate-limit reset.
+export function __resetProfileFallbackWarningsForTesting(): void {
+  profileFallbackWarned.clear()
+}

package/src/agent/multimodal/index.ts

@@ -0,0 +1,12 @@
+export { lookAtTool } from './look-at'
+export {
+  buildMultimodalLookerSystemPrompt,
+  imageInputSchema,
+  multimodalLookerPayloadSchema,
+  resolveImage,
+  URL_FETCH_MAX_BYTES,
+  URL_FETCH_TIMEOUT_MS,
+  type ImageInput,
+  type MultimodalLookerPayload,
+  type ResolvedImage,
+} from './looker'

package/src/agent/multimodal/look-at.ts

@@ -0,0 +1,185 @@
+import { Type } from '@mariozechner/pi-ai'
+import type { ImageContent } from '@mariozechner/pi-ai'
+import { defineTool } from '@mariozechner/pi-coding-agent'
+
+import { createSessionWithDispose, type SessionOrigin } from '@/agent'
+
+import { buildMultimodalLookerSystemPrompt, resolveImage, type ImageInput } from './looker'
+
+type ImageParam = { url: string } | { path: string } | { data: string; mimeType: string }
+
+type LookAtArgs = {
+  images: ImageParam[]
+  prompt?: string
+}
+
+type LookAtDetails = {
+  count: number
+  prompt?: string
+  text?: string
+  error?: string
+}
+
+// Routes an image-bearing turn to a vision-capable subagent so the main
+// session never sees the bytes. Saves main-agent context: when `models.default`
+// is text-only, this is the only way to get vision; when `models.default` IS
+// vision-capable, it still buys cheaper main-agent inference because the
+// image payload (which can be many KB after base64) only enters the vision
+// model's context.
+//
+// Output is the subagent's text response. The subagent itself decides whether
+// to answer the user's question (when `prompt` is supplied) or describe the
+// image (when `prompt` is omitted) via its dynamic system prompt.
+export const lookAtTool = defineTool({
+  name: 'look_at',
+  label: 'Look at images',
+  description:
+    'Route image(s) through a vision-capable subagent and get a text result. ' +
+    'Use this when you need to see an image: a screenshot the user shared, a diagram in a doc, a photo, a chart, etc. ' +
+    'Each image is specified by ONE of `url` (https://...), `path` (absolute filesystem path), or `data`+`mimeType` (base64). ' +
+    'The optional `prompt` is a question to ask about the image(s); without it, the subagent returns a faithful description. ' +
+    'The image bytes never enter your context — only the resulting text comes back.',
+  parameters: Type.Object({
+    images: Type.Array(
+      Type.Object({
+        url: Type.Optional(Type.String({ description: 'https:// URL to fetch the image from.' })),
+        path: Type.Optional(Type.String({ description: 'Absolute filesystem path (inside /agent or a mounted dir).' })),
+        data: Type.Optional(Type.String({ description: 'Base64-encoded image bytes (pair with mimeType).' })),
+        mimeType: Type.Optional(Type.String({ description: 'MIME type when using `data` (e.g. "image/png").' })),
+      }),
+      { minItems: 1, description: 'One or more images to look at.' },
+    ),
+    prompt: Type.Optional(
+      Type.String({
+        description:
+          'Optional question to ask about the image(s). When omitted, the subagent returns a faithful description.',
+      }),
+    ),
+  }),
+
+  async execute(_toolCallId, params, signal) {
+    const args = params as LookAtArgs
+    try {
+      const imageInputs = args.images.map(toImageInput)
+      const resolved = await Promise.all(imageInputs.map((i) => resolveImage(i, signal)))
+      const imageContents: ImageContent[] = resolved.map((r) => ({
+        type: 'image' as const,
+        data: r.data,
+        mimeType: r.mimeType,
+      }))
+
+      const systemPrompt = buildMultimodalLookerSystemPrompt(args.prompt)
+      const userText =
+        args.prompt !== undefined && args.prompt.trim() !== ''
+          ? args.prompt.trim()
+          : 'Please describe the attached image(s).'
+
+      const origin: SessionOrigin = {
+        kind: 'subagent',
+        subagent: 'multimodal-looker',
+        parentSessionId: '<look-at-tool>',
+      }
+
+      const { session, dispose } = await createSessionWithDispose({
+        systemPromptOverride: systemPrompt,
+        origin,
+        profile: 'vision',
+        // Both knobs are required to fully disarm the subagent's tool surface:
+        // `customTools: []` blocks typeclaw's system tools (websearch/webfetch/
+        // look_at/restart/...) — without it, the look_at tool would recurse
+        // into itself. `tools: []` blocks pi-coding-agent's defaults
+        // (read/bash/edit/write) — without it, a vision model could be talked
+        // into running shell commands or editing files inside its short-lived
+        // session. The looker should only describe images, not act.
+        tools: [],
+        customTools: [],
+      })
+
+      try {
+        await session.prompt(userText, { images: imageContents })
+        const text = extractLastAssistantText(session.messages)
+        if (text === null) {
+          return errorResult('multimodal-looker returned no text response', {
+            count: resolved.length,
+            prompt: args.prompt,
+          })
+        }
+        return successResult(text, { count: resolved.length, prompt: args.prompt })
+      } finally {
+        session.dispose()
+        await dispose()
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      return errorResult(message, { count: args.images.length, prompt: args.prompt })
+    }
+  },
+})
+
+function toImageInput(p: ImageParam): ImageInput {
+  const hasUrl = 'url' in p && p.url !== undefined && p.url !== ''
+  const hasPath = 'path' in p && p.path !== undefined && p.path !== ''
+  const hasData = 'data' in p && p.data !== undefined && p.data !== ''
+  const hasMime = 'mimeType' in p && p.mimeType !== undefined && p.mimeType !== ''
+
+  // `data` and `mimeType` are paired — accept both as one source. `mimeType`
+  // alone with no `data` is rejected as an incomplete base64 spec.
+  const sources: string[] = []
+  if (hasUrl) sources.push('url')
+  if (hasPath) sources.push('path')
+  if (hasData || hasMime) sources.push('data+mimeType')
+
+  if (sources.length === 0) {
+    throw new Error('look_at: each image must specify exactly one of `url`, `path`, or `data`+`mimeType`')
+  }
+  if (sources.length > 1) {
+    throw new Error(
+      `look_at: each image must specify exactly one of \`url\`, \`path\`, or \`data\`+\`mimeType\` (got: ${sources.join(', ')})`,
+    )
+  }
+  if (hasUrl) return { kind: 'url', url: (p as { url: string }).url }
+  if (hasPath) return { kind: 'file', path: (p as { path: string }).path }
+  if (hasData && hasMime) {
+    return { kind: 'base64', data: (p as { data: string }).data, mimeType: (p as { mimeType: string }).mimeType }
+  }
+  throw new Error('look_at: base64 image requires both `data` and `mimeType`')
+}
+
+// Pulls the most recent assistant turn's text content. The subagent's reply
+// shows up here once `session.prompt()` resolves. Tool calls in the assistant
+// message are ignored — multimodal-looker's session has no tools wired in
+// (`tools: []` + `customTools: []` at session creation), so in practice this
+// is pure text plus optional thinking blocks (which we skip).
+function extractLastAssistantText(messages: ReadonlyArray<unknown>): string | null {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i] as { role?: unknown; content?: unknown } | undefined
+    if (msg === undefined || msg.role !== 'assistant') continue
+    const content = msg.content
+    if (!Array.isArray(content)) continue
+    const texts: string[] = []
+    for (const part of content) {
+      if (part !== null && typeof part === 'object' && (part as { type?: unknown }).type === 'text') {
+        const t = (part as { text?: unknown }).text
+        if (typeof t === 'string') texts.push(t)
+      }
+    }
+    if (texts.length > 0) return texts.join('\n').trim()
+  }
+  return null
+}
+
+function successResult(text: string, partial: Omit<LookAtDetails, 'text' | 'error'>) {
+  const details: LookAtDetails = { ...partial, text }
+  return {
+    content: [{ type: 'text' as const, text }],
+    details,
+  }
+}
+
+function errorResult(message: string, partial: Omit<LookAtDetails, 'text' | 'error'>) {
+  const details: LookAtDetails = { ...partial, error: message }
+  return {
+    content: [{ type: 'text' as const, text: `look_at failed: ${message}` }],
+    details,
+  }
+}