typeclaw 0.1.5 → 0.2.0

package/README.md

@@ -68,18 +68,20 @@ That's it. The agent is now alive, listening on a websocket, ready to receive pr
 
 ## CLI
 
-| Command            | Purpose                                                              |
-| ------------------ | -------------------------------------------------------------------- |
-| `typeclaw init`    | Scaffold a new agent folder                                          |
-| `typeclaw start`   | Build and run the container                                          |
-| `typeclaw stop`    | Stop the container                                                   |
-| `typeclaw restart` | `stop` then `start`                                                  |
-| `typeclaw status`  | Show container + daemon registration state                           |
-| `typeclaw logs`    | Stream container stdout/stderr with local timestamps; `-f` to follow |
-| `typeclaw tui`     | Attach a terminal UI over the agent's websocket                      |
-| `typeclaw shell`   | Open a shell inside the running container                            |
-| `typeclaw reload`  | Push a live config reload to the running agent                       |
-| `typeclaw compose` | Orchestrate multiple agents                                          |
+| Command                             | Purpose                                                                            |
+| ----------------------------------- | ---------------------------------------------------------------------------------- |
+| `typeclaw init`                     | Scaffold a new agent folder                                                        |
+| `typeclaw start`                    | Build and run the container                                                        |
+| `typeclaw stop`                     | Stop the container                                                                 |
+| `typeclaw restart`                  | `stop` then `start`                                                                |
+| `typeclaw status`                   | Show container + daemon registration state                                         |
+| `typeclaw logs`                     | Stream container stdout/stderr with local timestamps; `-f` to follow               |
+| `typeclaw tui`                      | Attach a terminal UI over the agent's websocket                                    |
+| `typeclaw shell`                    | Open a shell inside the running container                                          |
+| `typeclaw reload`                   | Push a live config reload to the running agent                                     |
+| `typeclaw compose`                  | Orchestrate multiple agents                                                        |
+| `typeclaw channel add <kind>`       | Wire a new channel adapter (Slack, Discord, Telegram, KakaoTalk)                   |
+| `typeclaw channel reauth kakaotalk` | Re-authenticate KakaoTalk after a stale-token 401 or to rotate the stored password |
 
 ## Configuration
 

package/auth.schema.json

@@ -233,6 +233,47 @@
                   },
                   "updated_at": {
                     "type": "string"
+                  },
+                  "email": {
+                    "type": "string"
+                  },
+                  "encryptedPassword": {
+                    "type": "object",
+                    "properties": {
+                      "v": {
+                        "type": "number",
+                        "const": 1
+                      },
+                      "alg": {
+                        "type": "string",
+                        "const": "AES-256-GCM"
+                      },
+                      "kid": {
+                        "type": "string"
+                      },
+                      "iv": {
+                        "type": "string"
+                      },
+                      "ciphertext": {
+                        "type": "string"
+                      },
+                      "authTag": {
+                        "type": "string"
+                      },
+                      "createdAt": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "v",
+                      "alg",
+                      "kid",
+                      "iv",
+                      "ciphertext",
+                      "authTag",
+                      "createdAt"
+                    ],
+                    "additionalProperties": false
                   }
                 },
                 "required": [

package/cron.schema.json

@@ -29,6 +29,10 @@
               "timezone": {
                 "type": "string"
               },
+              "scheduledByRole": {
+                "type": "string"
+              },
+              "scheduledByOrigin": {},
               "kind": {
                 "type": "string",
                 "const": "prompt"
@@ -69,6 +73,10 @@
               "timezone": {
                 "type": "string"
               },
+              "scheduledByRole": {
+                "type": "string"
+              },
+              "scheduledByOrigin": {},
               "kind": {
                 "type": "string",
                 "const": "exec"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/secrets.schema.json

@@ -233,6 +233,47 @@
                   },
                   "updated_at": {
                     "type": "string"
+                  },
+                  "email": {
+                    "type": "string"
+                  },
+                  "encryptedPassword": {
+                    "type": "object",
+                    "properties": {
+                      "v": {
+                        "type": "number",
+                        "const": 1
+                      },
+                      "alg": {
+                        "type": "string",
+                        "const": "AES-256-GCM"
+                      },
+                      "kid": {
+                        "type": "string"
+                      },
+                      "iv": {
+                        "type": "string"
+                      },
+                      "ciphertext": {
+                        "type": "string"
+                      },
+                      "authTag": {
+                        "type": "string"
+                      },
+                      "createdAt": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "v",
+                      "alg",
+                      "kid",
+                      "iv",
+                      "ciphertext",
+                      "authTag",
+                      "createdAt"
+                    ],
+                    "additionalProperties": false
                   }
                 },
                 "required": [

package/src/agent/auth.ts

@@ -23,12 +23,18 @@ function secretsJsonPath(): string {
   return join(process.cwd(), 'secrets.json')
 }
 
-let cached: Auth | null = null
+// Per-provider cache. Sessions that use a profile mapped to provider X share
+// a single AuthStorage + ModelRegistry for that provider; first use of a new
+// provider lazily resolves its credentials. This replaces the singleton
+// `getAuth()` from before multi-model — the singleton couldn't represent
+// "auth for `default` is OpenAI, auth for `vision` is Fireworks" without
+// constructing both at boot.
+const cached = new Map<KnownProviderId, Auth>()
+
+export function getAuthFor(providerId: KnownProviderId): Auth {
+  const existing = cached.get(providerId)
+  if (existing) return existing
 
-export function getAuth(): Auth {
-  if (cached) return cached
-
-  const providerId = providerForModelRef(getConfig().model)
   const provider = KNOWN_PROVIDERS[providerId]
 
   if (process.env.NODE_ENV === 'test' && !hasAnyCredentialInEnv(provider.apiKeyEnv)) {
@@ -37,8 +43,9 @@ export function getAuth(): Auth {
       authStorage.setRuntimeApiKey(provider.id, TEST_DUMMY_API_KEY)
     }
     const modelRegistry = ModelRegistry.create(authStorage)
-    cached = { authStorage, modelRegistry }
-    return cached
+    const auth = { authStorage, modelRegistry }
+    cached.set(providerId, auth)
+    return auth
   }
 
   const authStorage = createSecretsStoreForAgent(secretsJsonPath())
@@ -53,16 +60,11 @@ export function getAuth(): Auth {
   // is set. OAuth credentials in the file still take precedence on read
   // because AuthStorage's hasAuth checks runtimeOverrides first only for
   // api-key-shaped credentials — OAuth on disk wins on its own.
-  //
-  // The previous code branch that wrote the env value into secrets.json and
-  // stripped the matching `.env` line has been removed. Env values stay in
-  // env; the file stays user-owned. See src/secrets/hydrate.ts for the same
-  // policy on the channels side.
   if (supportsApiKey(provider) && provider.apiKeyEnv) {
     const envKey = process.env[provider.apiKeyEnv]
     if (envKey !== undefined && envKey !== '') {
-      const existing = authStorage.get(provider.id)
-      if (existing === undefined || existing.type === 'api_key') {
+      const existingCred = authStorage.get(provider.id)
+      if (existingCred === undefined || existingCred.type === 'api_key') {
         authStorage.setRuntimeApiKey(provider.id, envKey)
       }
     }
@@ -74,12 +76,20 @@ export function getAuth(): Auth {
   }
 
   const modelRegistry = ModelRegistry.create(authStorage)
-  cached = { authStorage, modelRegistry }
-  return cached
+  const auth = { authStorage, modelRegistry }
+  cached.set(providerId, auth)
+  return auth
+}
+
+// Back-compat shim for callers that still want the `default` profile's auth
+// (the main session path). Equivalent to `getAuthFor(provider-of-default)`.
+export function getAuth(): Auth {
+  const defaultRef = getConfig().models.default
+  return getAuthFor(providerForModelRef(defaultRef))
 }
 
 export function resetAuthForTesting(): void {
-  cached = null
+  cached.clear()
 }
 
 function hasAnyCredentialInEnv(apiKeyEnv: string | null): boolean {
@@ -88,19 +98,32 @@ function hasAnyCredentialInEnv(apiKeyEnv: string | null): boolean {
 
 function missingCredentialMessage(providerId: KnownProviderId): string {
   const provider = KNOWN_PROVIDERS[providerId]
-  const ref = getConfig().model
-  const slash = ref.indexOf('/')
+  const defaultRef = getConfig().models.default
+  const defaultProviderId = providerForModelRef(defaultRef)
+  // For the `default` profile, name the model in the error message (matches
+  // pre-multi-model behavior). For any other profile, the user is mixing
+  // providers across profiles and the error must name the failing provider
+  // without claiming it's tied to the `default` model.
+  const isDefault = defaultProviderId === providerId
+  const ref = isDefault ? defaultRef : null
   const modelName =
-    (provider.models as Record<string, { name: string }>)[ref.slice(slash + 1)]?.name ?? ref.slice(slash + 1)
+    ref !== null
+      ? ((provider.models as Record<string, { name: string }>)[ref.slice(ref.indexOf('/') + 1)]?.name ??
+        ref.slice(ref.indexOf('/') + 1))
+      : null
 
   const oauthOnly = supportsOAuth(provider) && !supportsApiKey(provider)
   const apiKeyOnly = supportsApiKey(provider) && !supportsOAuth(provider)
 
   if (oauthOnly) {
-    return `No credentials for ${provider.name}. Run \`typeclaw init\` and pick "OAuth" to log in to ${modelName}.`
+    return modelName
+      ? `No credentials for ${provider.name}. Run \`typeclaw init\` and pick "OAuth" to log in to ${modelName}.`
+      : `No credentials for ${provider.name} (referenced by a non-default profile). Run \`typeclaw init\` and pick "OAuth" to log in.`
   }
   if (apiKeyOnly && provider.apiKeyEnv) {
-    return `Set ${provider.apiKeyEnv} in .env (or secrets.json#providers.${provider.id}.key.value) to use ${modelName} via ${provider.name}.`
+    return modelName
+      ? `Set ${provider.apiKeyEnv} in .env (or secrets.json#providers.${provider.id}.key.value) to use ${modelName} via ${provider.name}.`
+      : `Set ${provider.apiKeyEnv} in .env (or secrets.json#providers.${provider.id}.key.value) to use ${provider.name} (referenced by a non-default profile).`
   }
   return `No credentials for ${provider.name}. Either set ${provider.apiKeyEnv ?? '<api-key-env>'} in .env or run \`typeclaw init\` and pick "OAuth".`
 }

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()
+}