typeclaw 0.36.7 → 0.37.0

package/src/portbroker/protocol.ts

@@ -15,6 +15,7 @@ export type HostdToContainer =
 export type ContainerToHostd =
   | { type: 'broker-hello-ack' }
   | { type: 'broker-hello-nack'; reason: string }
+  | { type: 'port-forward-request'; targetPort: number; hostCandidates: number[]; reason?: string }
   | { type: 'port-listen-snapshot'; ports: Array<{ port: number; bindAddr: BindAddr }> }
   | { type: 'port-listen-opened'; port: number; bindAddr: BindAddr }
   | { type: 'port-listen-closed'; port: number }
@@ -24,8 +25,14 @@ export type ContainerToHostd =
   | { type: 'relay-close'; streamId: StreamId; side: 'upstream' | 'downstream' }
 
 export type PortForwardEvent =
-  | { kind: 'port-forward-opened'; containerName: string; port: number; bindAddr: BindAddr }
-  | { kind: 'port-forward-closed'; containerName: string; port: number; reason: PortForwardCloseReason }
+  | { kind: 'port-forward-opened'; containerName: string; port: number; hostPort: number; bindAddr: BindAddr }
+  | {
+      kind: 'port-forward-closed'
+      containerName: string
+      port: number
+      hostPort: number
+      reason: PortForwardCloseReason
+    }
   | { kind: 'port-forward-failed'; containerName: string; port: number; reason: string }
 
 export type PortForwardCloseReason = 'container-released' | 'host-error' | 'deregistered' | 'broker-stopped'

package/src/run/channel-session-factory.ts

@@ -3,6 +3,7 @@ import { SessionManager } from '@mariozechner/pi-coding-agent'
 import { createSession as defaultCreateSession } from '@/agent'
 import type { LiveSessionRegistry } from '@/agent/live-sessions'
 import type { LiveSubagentRegistry } from '@/agent/live-subagents'
+import { sessionMetaPayload } from '@/agent/session-meta'
 import type { CreateSessionForSubagent, SubagentRegistry } from '@/agent/subagents'
 import { capJsonlFileInPlace } from '@/bundled-plugins/tool-result-cap/cap-jsonl'
 import type { CapOptions } from '@/bundled-plugins/tool-result-cap/cap-result'
@@ -70,6 +71,9 @@ export type BuildChannelSessionFactoryDeps = {
   subagentRegistry?: SubagentRegistry
   getCreateSessionForSubagent?: () => CreateSessionForSubagent
   liveSessionRegistry?: LiveSessionRegistry
+  // Forwarded to createSession: when true the `# Memory` section is omitted
+  // from the system prompt (vector agents inject memory per-turn instead).
+  suppressSystemMemory?: boolean
 }
 
 // Tight basename validation so a tampered or corrupt channels/sessions.json
@@ -137,10 +141,16 @@ export function buildChannelSessionFactory(deps: BuildChannelSessionFactoryDeps)
       ...(deps.getCreateSessionForSubagent !== undefined
         ? { createSessionForSubagent: deps.getCreateSessionForSubagent() }
         : {}),
+      ...(deps.suppressSystemMemory !== undefined ? { suppressSystemMemory: deps.suppressSystemMemory } : {}),
     })
 
     const sessionId = sessionManager.getSessionId()
-    deps.liveSessionRegistry?.register({ sessionId, session })
+    deps.liveSessionRegistry?.register({
+      sessionId,
+      session,
+      origin: sessionMetaPayload(origin).origin,
+      registeredAtMs: Date.now(),
+    })
 
     return {
       session,

package/src/run/index.ts

@@ -5,6 +5,7 @@ import { LiveSessionRegistry } from '@/agent/live-sessions'
 import { LiveSubagentRegistry } from '@/agent/live-subagents'
 import { requestContainerRestart } from '@/agent/restart'
 import { consumeRestartHandoff } from '@/agent/restart-handoff'
+import { sessionMetaPayload } from '@/agent/session-meta'
 import type { SessionOrigin } from '@/agent/session-origin'
 import {
   awaitWithSubagentTimeout,
@@ -18,6 +19,9 @@ import {
   type SubagentShared,
 } from '@/agent/subagents'
 import { clearTodosForOrigin } from '@/agent/todo/continuation-wiring'
+import { vectorEnabledFromMemoryConfig } from '@/bundled-plugins/memory/vector/config'
+import { embed, warmEmbedder } from '@/bundled-plugins/memory/vector/embedder'
+import { buildStartupVectorIndex } from '@/bundled-plugins/memory/vector/startup'
 import { resolveCapOptionsFromConfig } from '@/bundled-plugins/tool-result-cap'
 import {
   createChannelManager,
@@ -55,7 +59,7 @@ import { runStartupMigrations } from '@/migrations'
 import { loadPlugins, type LoadPluginsResult, pluginCronJobs, type PluginRegistry, summarizeLoaded } from '@/plugin'
 import { createPluginLogger } from '@/plugin/context'
 import type { CronHandlerContext } from '@/plugin/types'
-import { createContainerBroker, publishForwardResult } from '@/portbroker'
+import { createContainerBroker, publishForwardResult, subscribeForwardRequest } from '@/portbroker'
 import { formatChannelReloadSummary, ReloadRegistry } from '@/reload'
 import { createClaimController } from '@/role-claim'
 import {
@@ -157,6 +161,10 @@ export async function startAgent({
   const tuiTokenOpt = tuiToken !== undefined && tuiToken !== '' ? { tuiToken } : {}
 
   const pluginConfigsByName = loadPluginConfigsSync(cwd)
+  // Vector agents omit the system-prompt `# Memory` section and inject memory
+  // per-turn instead. Derived once here: `memory.vector.enabled` is
+  // restart-required, so a single boot read is coherent for the process.
+  const suppressSystemMemory = vectorEnabledFromMemoryConfig(pluginConfigsByName.memory)
   const cwdConfig = loadConfigSync(cwd)
   const githubTokenBridge = createGithubTokenBridge()
   const mcpManager =
@@ -215,6 +223,19 @@ export async function startAgent({
   // v2-only parser rejects the file and hydrate below sees no channels. Runs
   // exactly once per folder; a folder already at v2 is a no-op.
   runStartupMigrations(cwd)
+  if (suppressSystemMemory) {
+    await buildStartupVectorIndex(cwd, embed).catch((err) => {
+      console.warn(`[vector] startup index build failed: ${err instanceof Error ? err.message : String(err)}`)
+    })
+
+    // Warm the embedder now (even when the index needed no rebuild above, which
+    // skips embed() entirely) so the first channel turn's query embed doesn't
+    // pay the one-time ONNX init on its critical path. Non-fatal: a failure here
+    // degrades to the per-turn lazy load, same as before this step existed.
+    await warmEmbedder().catch((err) => {
+      console.warn(`[vector] embedder warm-up failed: ${err instanceof Error ? err.message : String(err)}`)
+    })
+  }
 
   // Channel adapters read `process.env[TOKEN_ENV]` (see channels/manager.ts).
   // Hydrate fills any unset env var from secrets.json#channels via env-wins:
@@ -280,6 +301,7 @@ export async function startAgent({
       stream,
       reloadRegistry,
       pluginRuntime,
+      suppressSystemMemory,
       getChannelRouter: () => channelManager.router,
       rehydrateCapOptions: resolveCapOptionsFromConfig(pluginConfigsByName['tool-result-cap']),
       permissions: pluginsLoaded.permissions,
@@ -394,7 +416,12 @@ export async function startAgent({
         ...(entry.pluginSubagent.bashPolicy !== undefined ? { bashPolicy: entry.pluginSubagent.bashPolicy } : {}),
         ...runtimeVersionOpt,
       })
-      liveSessionRegistry.register({ sessionId, session: created.session })
+      liveSessionRegistry.register({
+        sessionId,
+        session: created.session,
+        origin: sessionMetaPayload(origin).origin,
+        registeredAtMs: Date.now(),
+      })
       const originalDispose = created.dispose
       return {
         ...created,
@@ -485,6 +512,7 @@ export async function startAgent({
             containerName: containerNameOpt.containerName,
             sessionFactory,
             channelRouter: channelManager.router,
+            suppressSystemMemory,
             ...mcpManagerOpt,
           }),
         subagent: (subName: string, payload?: unknown) =>
@@ -525,6 +553,7 @@ export async function startAgent({
         channelRouter: channelManager.router,
         origin: cronOrigin,
         permissions: pluginsLoaded.permissions,
+        suppressSystemMemory,
         ...(refOverride !== undefined ? { refOverride } : {}),
         ...(snap.hasAnyPluginContent
           ? {
@@ -543,7 +572,12 @@ export async function startAgent({
         ...runtimeVersionOpt,
         ...mcpManagerOpt,
       })
-      liveSessionRegistry.register({ sessionId, session })
+      liveSessionRegistry.register({
+        sessionId,
+        session,
+        origin: sessionMetaPayload(cronOrigin).origin,
+        registeredAtMs: Date.now(),
+      })
       return {
         prompt: (text) => session.prompt(text),
         dispose: () => {
@@ -729,11 +763,10 @@ export async function startAgent({
               payload: { kind: 'portbroker-log', event },
             })
           },
-          // Re-publish to the in-process bus so consumers (today: the
-          // agent-browser plugin's bind-with-forward retry loop) can subscribe
-          // without holding a reference to the broker. See src/portbroker/
-          // forward-result-bus.ts for the contract.
+          // Re-publish to in-process buses so plugin code can talk to the
+          // broker without holding a ContainerBroker reference.
           onForwardResult: (event) => publishForwardResult(event),
+          onForwardRequestSubscribe: (cb) => subscribeForwardRequest(cb),
         })
       : undefined
   const containerBrokerOpt = containerBroker ? { containerBroker } : {}
@@ -749,6 +782,7 @@ export async function startAgent({
       outbound,
       sessionFactory,
       channelRouter: channelManager.router,
+      suppressSystemMemory,
       ...mcpManagerOpt,
     })
 

package/src/server/command-runner.ts

@@ -55,6 +55,10 @@ export type CommandRunnerOptions = {
   // wire for the handler/command path.
   channelRouter: ChannelRouter | undefined
   mcpManager?: McpManager
+  // When true, prompt sessions spawned here omit the system-prompt `# Memory`
+  // section (vector agents inject memory per-turn). Forwarded to createSession
+  // so command/handler sessions stay coherent with the rest of the runtime.
+  suppressSystemMemory?: boolean
 }
 
 type CommandHandle = {
@@ -194,6 +198,7 @@ export function createCommandRunner(opts: CommandRunnerOptions): CommandRunner {
               signal: abortController.signal,
               sessionFactory: opts.sessionFactory,
               channelRouter: opts.channelRouter,
+              ...(opts.suppressSystemMemory !== undefined ? { suppressSystemMemory: opts.suppressSystemMemory } : {}),
               ...(opts.mcpManager !== undefined ? { mcpManager: opts.mcpManager } : {}),
             }),
           subagent: (subName, payload) =>
@@ -380,6 +385,7 @@ export async function runPromptForCommand(args: {
   // so the spawned session exposes `channel_send`.
   channelRouter?: ChannelRouter
   mcpManager?: McpManager
+  suppressSystemMemory?: boolean
   // Test seam for the agent-session boundary. Production passes the real
   // `createSessionWithDispose`; tests inject a fake to verify wiring
   // (specifically: the sessionManager handed off must be persisted, not
@@ -409,10 +415,27 @@ export async function runPromptForCommand(args: {
     ...(args.mcpManager !== undefined ? { mcpManager: args.mcpManager } : {}),
     ...(args.runtimeVersion !== undefined ? { runtimeVersion: args.runtimeVersion } : {}),
     ...(args.containerName !== undefined ? { containerName: args.containerName } : {}),
+    ...(args.suppressSystemMemory !== undefined ? { suppressSystemMemory: args.suppressSystemMemory } : {}),
   })
   const detachAbort = bindSignalToSession(args.signal, session)
+  // Mirror the other turn drivers (TUI/channel/cron/subagent): fire
+  // session.turn.start with a retrievalContext so a vector agent — whose
+  // system-prompt `# Memory` section is suppressed — gets its long-term memory
+  // injected per-turn into the user prompt here too. Without this, command and
+  // handler prompt sessions would have no memory at all under vector mode.
+  const turnEvent = { sessionId, agentDir: args.agentDir, origin: args.origin }
+  const retrievalContext = { results: '' }
   try {
-    await session.prompt(`${renderTurnTimeAnchor()}\n\n${args.text}`)
+    await snapshot.hooks.runSessionTurnStart({ ...turnEvent, userPrompt: args.text, retrievalContext })
+    const turnText =
+      retrievalContext.results.length > 0
+        ? `${renderTurnTimeAnchor()}\n\n${args.text}\n\n${retrievalContext.results}`
+        : `${renderTurnTimeAnchor()}\n\n${args.text}`
+    try {
+      await session.prompt(turnText)
+    } finally {
+      await snapshot.hooks.runSessionTurnEnd(turnEvent)
+    }
     return session.getLastAssistantText() ?? ''
   } finally {
     detachAbort()

package/src/server/index.ts

@@ -15,6 +15,7 @@ import { forgetSharedLoopGuardTool } from '@/agent/plugin-tools'
 import { detectProviderError } from '@/agent/provider-error'
 import { requestContainerRestart } from '@/agent/restart'
 import { consumeRestartHandoff, type RestartHandoff } from '@/agent/restart-handoff'
+import { sessionMetaPayload } from '@/agent/session-meta'
 import type { SessionOrigin } from '@/agent/session-origin'
 import { parseSubagentCompletedPayload, renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
 import type { CreateSessionForSubagent } from '@/agent/subagents'
@@ -541,7 +542,12 @@ export function createServer({
               state.unsubTurnOutcome = subscribeTurnOutcome(session, agentDir, origin, sessionFileId, logger)
             }
 
-            liveSessionRegistry?.register({ sessionId: sessionFileId, session })
+            liveSessionRegistry?.register({
+              sessionId: sessionFileId,
+              session,
+              origin: sessionMetaPayload(origin).origin,
+              registeredAtMs: Date.now(),
+            })
             forwardSessionEvents(ws, state, logger, sessionFileId)
 
             if (stream) {
@@ -760,17 +766,23 @@ export function createServer({
             }
             send(ws, { type: 'prompt_started', messageId: `local-${crypto.randomUUID()}`, text: msg.text })
             const fallbackHooks = state.runtimeSnapshot?.hooks
+            const retrievalContext: { results: string } = { results: '' }
             if (fallbackHooks !== undefined && agentDir !== undefined) {
               await fallbackHooks.runSessionTurnStart({
                 sessionId: state.sessionFileId,
                 agentDir,
                 userPrompt: msg.text,
                 origin: state.origin,
+                retrievalContext,
               })
             }
             state.lastUsage = null
             try {
-              await state.session.prompt(`${renderTurnTimeAnchor()}\n\n${msg.text}`)
+              const turnText =
+                retrievalContext.results.length > 0
+                  ? `${renderTurnTimeAnchor()}\n\n${msg.text}\n\n${retrievalContext.results}`
+                  : `${renderTurnTimeAnchor()}\n\n${msg.text}`
+              await state.session.prompt(turnText)
               send(ws, doneMessage(state))
             } catch (err) {
               const message = err instanceof Error ? err.message : String(err)
@@ -1019,15 +1031,24 @@ function makeIdleHookCaller(state: SessionState): () => Promise<void> {
 function makeTurnHookCallers(
   state: SessionState,
   agentDir: string | undefined,
-): { fireTurnStart: (userPrompt: string) => Promise<void>; fireTurnEnd: () => Promise<void> } {
+): { fireTurnStart: (userPrompt: string) => Promise<{ results: string }>; fireTurnEnd: () => Promise<void> } {
   const hooks: HookBus | undefined = state.runtimeSnapshot?.hooks
   if (hooks === undefined || agentDir === undefined) {
-    return { fireTurnStart: async () => {}, fireTurnEnd: async () => {} }
+    return { fireTurnStart: async () => ({ results: '' }), fireTurnEnd: async () => {} }
   }
   const turnEndEvent = { sessionId: state.sessionFileId, agentDir, origin: state.origin }
   return {
-    fireTurnStart: (userPrompt) =>
-      hooks.runSessionTurnStart({ sessionId: state.sessionFileId, agentDir, userPrompt, origin: state.origin }),
+    fireTurnStart: async (userPrompt) => {
+      const retrievalContext = { results: '' }
+      await hooks.runSessionTurnStart({
+        sessionId: state.sessionFileId,
+        agentDir,
+        userPrompt,
+        origin: state.origin,
+        retrievalContext,
+      })
+      return retrievalContext
+    },
     fireTurnEnd: () => hooks.runSessionTurnEnd(turnEndEvent),
   }
 }
@@ -1058,10 +1079,14 @@ async function drain(
         }).catch((err) => logger.error(`[server] ${state.sessionFileId}: todo turn-start failed: ${describeErr(err)}`))
       }
 
-      await fireTurnStart(item.text)
+      const retrievalContext = await fireTurnStart(item.text)
       state.lastUsage = null
       try {
-        await state.session.prompt(`${renderTurnTimeAnchor()}\n\n${item.text}`)
+        const turnText =
+          retrievalContext.results.length > 0
+            ? `${renderTurnTimeAnchor()}\n\n${item.text}\n\n${retrievalContext.results}`
+            : `${renderTurnTimeAnchor()}\n\n${item.text}`
+        await state.session.prompt(turnText)
         send(ws, doneMessage(state))
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err)
@@ -1269,6 +1294,15 @@ function handleInspectMessage(
     sendInspect(ws, { type: 'pong', id: msg.id })
     return
   }
+  if (msg.type === 'list_live') {
+    const sessions = (liveSessionRegistry?.listLive() ?? []).map((e) => ({
+      sessionId: e.sessionId,
+      origin: e.origin!,
+      registeredAtMs: e.registeredAtMs ?? 0,
+    }))
+    sendInspect(ws, { type: 'live_sessions', sessions })
+    return
+  }
   if (msg.type !== 'subscribe' || typeof msg.sessionId !== 'string' || msg.sessionId === '') {
     sendInspect(ws, { type: 'error', message: 'invalid inspect subscription' })
     ws.close()

package/src/shared/index.ts

@@ -14,6 +14,8 @@ export {
   type InspectClientMessage,
   type InspectFramePayload,
   type InspectServerMessage,
+  type LiveSessionOriginPayload,
+  type LiveSessionPayload,
   type PromptDelivery,
   type QueueStateItem,
   type ReloadResultPayload,

package/src/shared/protocol.ts

@@ -60,6 +60,36 @@ export type InspectClientMessage =
   // distinguish "idle" from "dead"; a missed pong can. Guards a wedged
   // WebSocket that stays ESTABLISHED yet never fires 'close'/'error'.
   | { type: 'ping'; id: number }
+  // One-shot query for sessions live in the container's registry but not yet on
+  // disk (pi-coding-agent defers the first .jsonl write to the first assistant
+  // message). Lets the host-stage inspect picker show in-flight sessions before
+  // their reply lands. Answered with a single `live_sessions` reply.
+  | { type: 'list_live' }
+
+// Wire mirror of MinimalSessionOrigin (@/agent/session-meta). Duplicated rather
+// than imported because @/shared is a leaf module — @/agent depends on it, so
+// importing back would create a cycle. A compile-time assertion in session-meta
+// keeps the two structurally in sync; drift fails typecheck.
+export type LiveSessionOriginPayload =
+  | { kind: 'tui' }
+  | { kind: 'cron'; jobId: string; jobKind: 'prompt' | 'exec' | 'subagent' | 'handler' }
+  | {
+      kind: 'channel'
+      adapter: string
+      workspace: string
+      workspaceName?: string
+      chat: string
+      chatName?: string
+      thread: string | null
+    }
+  | { kind: 'subagent'; subagent: string; parentSessionId: string }
+  | { kind: 'system'; component: string }
+
+export type LiveSessionPayload = {
+  sessionId: string
+  origin: LiveSessionOriginPayload
+  registeredAtMs: number
+}
 
 export type InspectFramePayload =
   | { kind: 'text_delta'; sessionId: string; delta: string }
@@ -137,6 +167,7 @@ export type InspectServerMessage =
   | { type: 'frame'; ts: number; payload: InspectFramePayload }
   | { type: 'error'; message: string }
   | { type: 'pong'; id: number }
+  | { type: 'live_sessions'; sessions: LiveSessionPayload[] }
 
 export type ClientMessage =
   | { type: 'prompt'; text: string; delivery?: PromptDelivery }

package/src/skills/typeclaw-channels/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-channels
-description: "TypeClaw channel behavior: how the agent decides to engage vs. stay silent on external messenger inbound (Discord, Slack, Telegram, KakaoTalk). Covers the `channels.<adapter>.engagement` triggers (mention/reply/dm), reply stickiness, the non-configurable solo-human fallback, history-prefetch windows, and the `alias` system — plain-text names the agent answers to, substring match semantics, peer-name suppressors, and engagement priority. Load when the user asks why the agent did or did not respond in a channel, wants to change when it auto-replies, asks to 'be quieter'/'stop auto-replying', wants it to answer to a nickname, or mentions engagement, stickiness, aliases, mentions, trigger words, suppressors, or '응답', '호출', '채널', '별칭', '왜 답을 안 해'. Access control (who is admitted at all) lives in `roles` — see typeclaw-permissions. The `channels`/`alias` schema, defaults, and safe-edit workflow live in typeclaw-config."
+description: "TypeClaw channel behavior: how the agent decides to engage vs. stay silent on external messenger inbound (Discord, Slack, Telegram, LINE, KakaoTalk). Covers the `channels.<adapter>.engagement` triggers (mention/reply/dm), reply stickiness, the non-configurable solo-human fallback, history-prefetch windows, and the `alias` system — plain-text names the agent answers to, substring match semantics, peer-name suppressors, and engagement priority. Load when the user asks why the agent did or did not respond in a channel, wants to change when it auto-replies, asks to 'be quieter'/'stop auto-replying', wants it to answer to a nickname, or mentions engagement, stickiness, aliases, mentions, trigger words, suppressors, or '응답', '호출', '채널', '별칭', '왜 답을 안 해'. Access control (who is admitted at all) lives in `roles` — see typeclaw-permissions. The `channels`/`alias` schema, defaults, and safe-edit workflow live in typeclaw-config."
 ---
 
 # typeclaw-channels
@@ -16,7 +16,7 @@ Both `channels` and `alias` are **live-reloadable** — edits take effect on the
 
 ## Channels
 
-`channels` configures which external messenger adapters are enabled and how the engagement layer should behave on each. **Access control lives in `roles`, not here** — to admit a chat, declare a role match-rule that covers it (see `typeclaw-permissions`). The shape is `channels: { "<adapter-id>": { engagement, history, enabled } }`. Today the adapters are `discord-bot`, `slack-bot`, `telegram-bot`, and `kakaotalk`.
+`channels` configures which external messenger adapters are enabled and how the engagement layer should behave on each. **Access control lives in `roles`, not here** — to admit a chat, declare a role match-rule that covers it (see `typeclaw-permissions`). The shape is `channels: { "<adapter-id>": { engagement, history, enabled } }`. Today the adapters are `discord-bot`, `slack-bot`, `telegram-bot`, `line`, and `kakaotalk`.
 
 The channels block is **live-reloadable** — edits take effect on the next `reload`, no container restart.
 
@@ -78,8 +78,8 @@ This says: the `discord-bot` adapter is enabled with default engagement; one spe
 
 This is a **`roles`** edit, not a `channels` edit. See the `typeclaw-permissions` skill for the full procedure. Short version:
 
-1. Get the platform ID (Discord channel ID, Slack channel ID, Telegram chat ID, KakaoTalk chat ID).
-2. Append a match-rule to `roles.member.match` using the canonical DSL (`discord:<guild>/<channel>`, `slack:<team>/<channel>`, `telegram:<chat>`, `kakao:<chat>`). Pass `acknowledgeGuards: { rolePromotion: true }` in the `write`/`edit` args — the `rolePromotion` security guard blocks any widening of `roles.<role>.match` without an ack (see `typeclaw-permissions`).
+1. Get the platform ID (Discord channel ID, Slack channel ID, Telegram chat ID, LINE chat ID, KakaoTalk chat ID).
+2. Append a match-rule to `roles.member.match` using the canonical DSL (`discord:<guild>/<channel>`, `slack:<team>/<channel>`, `telegram:<chat>`, for LINE the bucketed form `line:dm/<chatId>`, `line:group/<chatId>`, or `line:square/<chatId>` — pick the bucket from the chat's classification; an unbucketed `line:<chatId>` is read as a workspace and never matches — and `kakao:<chat>`). Pass `acknowledgeGuards: { rolePromotion: true }` in the `write`/`edit` args — the `rolePromotion` security guard blocks any widening of `roles.<role>.match` without an ack (see `typeclaw-permissions`).
 3. **`roles.<role>.match[]` edits are live-reloadable** — they take effect on the next `typeclaw reload` (the classifier marks `roles.match` as `applied`, and the permission service rebuilds its role table). Only `roles.<role>.permissions[]` edits are restart-required. So adding a match-rule to admit a channel applies on `reload`; no container restart needed.
 
 ### When the user asks "stop replying in this channel"

package/src/skills/typeclaw-config/SKILL.md

@@ -18,7 +18,7 @@ The runtime reads `typeclaw.json` at container startup. Some fields are picked u
 - `mounts` — additional host directories the user has chosen to expose to you. Each entry produces a `docker run -v <hostPath>:/agent/mounts/<name>` flag at `typeclaw start` time, so the directory shows up at `mounts/<name>` inside your agent folder. **The launcher reads this; the running container does not.** Editing `mounts` only takes effect on the next `typeclaw start`. **Restart-required.**
 - `plugins` — array of plugin module specifiers loaded at server boot: npm package names for published plugins, or relative paths for local plugins you are authoring. **Restart-required.**
 - `alias` — additional names the agent answers to when a channel message contains its name in plain text (no `<@id>` mention). The agent folder's directory name (`basename(agentDir)`) is always implicit; `alias` adds further forms (Latin transliteration, nicknames, Korean particles, etc.). Used by the channel engagement layer alongside the structural mention/reply/dm triggers. **Live-reloadable.**
-- `channels` — per-adapter engagement triggers and history-prefetch knobs for external messengers (Discord, Slack, Telegram, KakaoTalk), plus the GitHub channel (a webhook-driven adapter that watches repos and reviews PRs — see **GitHub channel** below). Access control lives in `roles`, not here. **Live-reloadable** — edits take effect on the next `reload` without a container restart.
+- `channels` — per-adapter engagement triggers and history-prefetch knobs for external messengers (Discord, Slack, Telegram, LINE, KakaoTalk), plus the GitHub channel (a webhook-driven adapter that watches repos and reviews PRs — see **GitHub channel** below). Access control lives in `roles`, not here. **Live-reloadable** — edits take effect on the next `reload` without a container restart.
 - `docker.file` — controls what ships in the autogenerated container image. Two layers: (1) **toggles** for opinionated package installs — `tmux`, `gh`, `python`, `xvfb` default on (`true`); `cjkFonts` defaults to `"auto"` (resolved from host locale at start); `ffmpeg`, `cloudflared`, `claudeCode`, `codexCli` default off (`false`) — set a toggle to `false` to omit, or to a version string like `"2.40.0"` to apt-pin (`python`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, and `codexCli` are boolean-only). Most toggles install apt packages with BuildKit cache mounts; `cloudflared`, `claudeCode`, and `codexCli` are exceptions — `cloudflared` downloads the pinned GitHub release, `claudeCode` runs Anthropic's official `curl | bash` installer, `codexCli` `bun install`s the `@openai/codex` npm package. (2) **`append`** — extra Dockerfile lines spliced in right before `ENTRYPOINT` for anything the toggles don't cover. The whole Dockerfile is rewritten on every `start` from the typeclaw template. Lives under the `docker` namespace alongside future Docker-related blocks (e.g. `docker.compose`). **Restart-required** (next `typeclaw start` rebuilds the image).
 - `git.ignore.append` — extra `.gitignore` patterns `typeclaw start` splices into the TypeClaw-owned `.gitignore` before the protected TypeClaw rules. The whole `.gitignore` is rewritten and auto-committed on every `start` when it changes; `append` is the supported escape hatch for local ignore patterns without editing the managed file by hand. Lives under the `git` namespace. **Restart-required** (next `typeclaw start` refreshes and commits `.gitignore`).
 - `portForward` — allow/deny policy for the auto port-forwarder (the host-stage `_hostd` daemon's portbroker). When the agent runs a server inside the container that LISTENs on a TCP port, the broker proxies it to the same port number on `127.0.0.1` of the host so the user can hit it directly. `portForward` decides which ports are allowed through. **Restart-required** — the broker captures the policy at register time on `typeclaw start`.
@@ -134,7 +134,7 @@ The reference is **a lookup table, not a wishlist** — recommending a path ther
 
 ## Channels and Alias
 
-`channels` configures which external adapters (`discord-bot`, `slack-bot`, `telegram-bot`, `kakaotalk`, and `github`) are enabled and how the engagement layer behaves on each; `alias` lists plain-text names the agent answers to. Both are **live-reloadable** — edits take effect on the next `reload`, no container restart.
+`channels` configures which external adapters (`discord-bot`, `slack-bot`, `telegram-bot`, `line`, `kakaotalk`, and `github`) are enabled and how the engagement layer behaves on each; `alias` lists plain-text names the agent answers to. Both are **live-reloadable** — edits take effect on the next `reload`, no container restart.
 
 This skill owns only the **schema and edit mechanics** of these two fields (see the schema table above): `channels: { "<adapter-id>": { engagement, history, enabled } }` and `alias: [...]`. The **behavioral contract** for the messenger adapters — when the agent wakes to reply vs. observes, engagement triggers (mention/reply/dm), reply stickiness, the non-configurable solo-human fallback, alias substring-match semantics, and peer-name suppressors — lives in the **`typeclaw-channels`** skill. **Load `typeclaw-channels` before answering any "why did/didn't the agent respond", "make it quieter", "answer to this nickname", or engagement/alias-behavior question.** Editing the fields here still follows the standard safe-edit workflow (read whole file, validate, write back, commit); since both are live-reloadable, tell the user the change takes effect on the next `reload` — no container restart.
 

package/src/skills/typeclaw-memory/SKILL.md

@@ -9,7 +9,9 @@ The agent's long-term memory is sharded across files in `memory/topics/<slug>.md
 
 ## Reading
 
-The `# Memory` section of every system prompt comes from topic shards only. Undreamed daily-stream events are **not** injected — call `memory_search` when you need them. When total shard bytes are above the 16 KB injection budget (or when speaking in a channel), shard bodies are also dropped from the prompt — only the heading + `cites=N, days=N, lastReinforced=YYYY-MM-DD` shows; call `memory_search` to fetch the bodies you need. The same `memory_search` covers both surfaces (topic shards and undreamed stream events), so one tool call reaches everything.
+The `# Memory` section comes from topic shards only. Undreamed daily-stream events are **not** injected — call `memory_search` when you need them. When total shard bytes are above the 16 KB injection budget (or when speaking in a channel), shard bodies are dropped — only the heading + `cites=N, days=N, lastReinforced=YYYY-MM-DD` shows; call `memory_search` to fetch the bodies you need. The same `memory_search` covers both surfaces (topic shards and undreamed stream events), so one tool call reaches everything.
+
+**Where the `# Memory` section lives depends on `memory.vector.enabled`.** With vector **off** (default), it's part of the system prompt, snapshotted once at session creation. With vector **on**, it is removed from the system prompt and injected fresh into each **user turn** instead: under budget you get all shard bodies, over budget you get the top-K shards/fragments most relevant to the current message (hybrid vector + keyword search). This keeps the system-prompt cache prefix stable across a session and lets retrieval track the current topic instead of a stale session-start snapshot. Either way `memory_search` remains available on demand.
 
 ## Writing
 

package/src/skills/typeclaw-permissions/SKILL.md

@@ -63,7 +63,7 @@ For each user turn, the current speaker's effective role is delivered in the tur
 ```
 tui                                # any TUI session
 *                                  # any channel session, any platform
-<platform>:*                       # any chat on this platform (slack | discord | telegram | kakao)
+<platform>:*                       # any chat on this platform (slack | discord | telegram | line | kakao)
 <platform>:<workspace>             # one workspace, any chat
 <platform>:<workspace>/<chat>      # one specific chat
 <platform>:dm/*                    # any DM on this platform
@@ -74,7 +74,7 @@ kakao:open/*                       # any KakaoTalk open chat
 
 `cron`, `subagent`, and `subagent:<name>` are also valid parser shapes (they parse without error), but they do **not** grant a role to a running cron or subagent session — those resolve from stamped provenance (`scheduledByRole` / `spawnedByRole`) instead. Don't write those rules expecting them to admit traffic the way channel rules do.
 
-Within a single string, tokens are **AND**'d. Across multiple strings in `match[]`, they're **OR**'d. The platform names are exactly `slack | discord | telegram | kakao`. Workspace and chat coordinates are platform-native IDs (Slack team `T0123`, Discord guild `123456789012345678`, Telegram chat `42`, KakaoTalk chat hash) — **never** display names. If the user gives you a name, you need to resolve it to an ID before writing the match rule.
+Within a single string, tokens are **AND**'d. Across multiple strings in `match[]`, they're **OR**'d. The platform names are exactly `slack | discord | telegram | line | kakao`. Workspace and chat coordinates are platform-native IDs (Slack team `T0123`, Discord guild `123456789012345678`, Telegram chat `42`, LINE chat ID, KakaoTalk chat hash) — **never** display names. If the user gives you a name, you need to resolve it to an ID before writing the match rule.
 
 Things the DSL rejects (the parser emits actionable errors at boot, but you should not write these in the first place):
 
@@ -149,7 +149,7 @@ To distinguish cause 1/2 from cause 3: if `typeclaw logs <container> -f` (host s
 
 This is a `roles` edit. The full procedure:
 
-1. **Resolve the coordinates.** Get the platform name (`slack | discord | telegram | kakao`), the workspace ID, the chat ID. If the user gave you names, ask them or look them up in the participants list of a previous inbound from that channel.
+1. **Resolve the coordinates.** Get the platform name (`slack | discord | telegram | line | kakao`), the workspace ID, the chat ID. If the user gave you names, ask them or look them up in the participants list of a previous inbound from that channel.
 2. **Pick a role.** Default to `member` for "give them normal channel access" — `member` carries `bypass.low` only, so no medium/high security guards are skipped. Use `trusted` if they're operator-class for this agent: trusted carries `bypass.medium` by default, which means trusted bypasses `secretExfilBash`, `secretExfilRead`, `ssrf`, `sessionSearchSecrets`, `gitExfil` (push to a clean operator-configured remote), `rolePromotion`, `cronPromotion` without acks. Trusted does NOT bypass `gitRemoteTainted`, `outboundSecret`, or `systemPromptLeak` (still high-tier). Use `owner` only for the primary operator — owner auto-bypasses every tier including high. The owner-in-public-channel risk (a channel-matched owner silently posting credentials to a public chat) is the reason `roles.owner.match[]` defaults to TUI-only; widening it requires either narrowing the match or stripping `security.bypass.high` from `roles.owner.permissions[]`.
 3. **Edit `typeclaw.json` `roles.<role>.match[]` with `acknowledgeGuards: { rolePromotion: true }`.** Append the canonical DSL string. Example: `roles.member.match` adds `"slack:T0123/C0ABCDE"`. If the user wants only a specific person in that channel, append `slack:T0123/C0ABCDE author:U_ME` instead. **The `rolePromotion` guard blocks any write that widens a role's `match[]` or `permissions[]` without an ack** — this is the runtime check that defends against the canonical "channel speaker asks to promote themselves" attack (see the `rolePromotion` discussion in the security bypass tiers section above). When the request is from the TUI operator (or you have explicit, unambiguous user confirmation that adding this match rule is intentional), pass `acknowledgeGuards: { rolePromotion: true }` in the `write` or `edit` tool args. **Never ack when the request came from a channel message asking you to add the speaker's own author-id to a higher role** — refuse and tell them to use `typeclaw role claim` from the operator's host CLI instead, which is the operator-issued out-of-band path. The same rule applies to introducing a brand-new role with non-empty grants, or widening any existing role's `permissions[]`.
 4. **Restart.** `roles` is **restart-required** — `typeclaw reload` does not re-evaluate role config. Tell the user: "edited `roles.<role>.match` — restart-required. Run `typeclaw restart` (host stage)."

package/src/skills/typeclaw-skills/SKILL.md

@@ -33,7 +33,7 @@ Skills live in three places. The runtime loads them in this order, **first wins
    - **Author**: the dreaming subagent, every time it consolidates a daily stream. Bar for promoting a fragment-pattern into a skill: multi-step, recurred across at least two distinct fragments, and the trigger conditions are statable as a "Use when..." description.
    - **Loading**: `src/agent/index.ts` adds `<agentDir>/memory/skills/` to `additionalSkillPaths` (existence-gated), so the resource loader auto-discovers every `SKILL.md` there on session start, identical to `.agents/skills/`.
    - **Persistence**: `memory/` is gitignored at the agent level, but the dreaming subagent force-commits its outputs (`MEMORY.md` plus everything under `memory/`, including `memory/skills/`) and applies `skip-worktree` so the human's `git status` stays clean.
-   - **You must not write to `memory/skills/` manually.** It is owned by the dreaming subagent. Hand-authored content there will be ignored by the part of the system that dreaming reads (it consolidates from `memory/yyyy-MM-dd.md`, not from existing skill files), and the dreaming subagent may overwrite the same path on a future run. If you want a hand-authored skill, put it in `.agents/skills/`.
+   - **You must not write to `memory/skills/` manually.** It is owned by the dreaming subagent. Hand-authored content there will be ignored by the part of the system that dreaming reads (it consolidates from `memory/streams/yyyy-MM-dd.jsonl`, not from existing skill files), and the dreaming subagent may overwrite the same path on a future run. If you want a hand-authored skill, put it in `.agents/skills/`.
 
 The collision rule (first wins) means: if a downloaded skill happens to share a name with a bundled one, the bundled one still wins and the downloaded copy is silently dropped with a collision diagnostic. Useful as a safety net, but do not rely on it — pick non-colliding names.
 

package/src/skills/typeclaw-tunnels/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-tunnels
-description: Use when the user mentions tunnel, ngrok, webhook URL, cloudflared, expose to internet, show my friend, public URL, GitHub webhook, port forward to public, reverse proxy, trycloudflare, or making a container-local service reachable from the internet. Read it before suggesting tunnel add/remove/status/logs or editing typeclaw.json tunnels[].
+description: Use when the user mentions tunnel, ngrok, webhook URL, cloudflared, expose to internet, show my friend, public URL, GitHub webhook, port forward to public, reverse proxy, trycloudflare, or making a container-local service reachable from the internet. Read it before suggesting tunnel add/remove/status/logs or editing typeclaw.json tunnels[]. Also read it the moment a tunnel "doesn't work": a Cloudflare tunnel with no public URL usually means `cloudflared` was never baked into the image — it is opt-in (`docker.file.cloudflared`, default false), so a hand-added tunnel needs it set explicitly. Diagnose root cause by reading typeclaw.json + checking `command -v cloudflared` rather than trusting a single error line; tell the user to set `docker.file.cloudflared: true` and `typeclaw restart`; never curl/vendor cloudflared yourself or report a cryptic error as if the tunnel were down.
 ---
 
 # typeclaw-tunnels
@@ -107,6 +107,27 @@ Unhealthy logs often show:
 
 Use `typeclaw tunnel logs <name> -f` while restarting the agent if you need to watch URL discovery live.
 
+## Diagnosing "the tunnel doesn't work" (you, the agent)
+
+When a tunnel has no public URL, **diagnose the root cause directly — don't stop at a single error line.** The most common cause by far is that `cloudflared` was never baked into the image (it's opt-in; see below), not a runtime outage. These checks always work from your shell inside the container:
+
+1. **Read `typeclaw.json`.** Look at `tunnels[]` (is the tunnel even configured? which `provider`?) and `docker.file.cloudflared` (is it `true`?).
+2. **Check the binary:** `command -v cloudflared`. If a `cloudflare-quick` / `cloudflare-named` tunnel is configured but this prints nothing, the cloudflared layer was never installed — that is the root cause (see "### `cloudflared` is not installed" below).
+3. **Check the upstream is alive — but probe the right port per provider:**
+   - `cloudflare-quick`: the service must be listening on the tunnel's `upstreamPort` from `typeclaw.json` (e.g. `curl -sS -o /dev/null -w '%{http_code}' http://127.0.0.1:<upstreamPort>/`).
+   - `cloudflare-named`: there is **no** `upstreamPort` (the schema rejects it; the dashboard's Public Hostname mapping `localhost:<port>` captures the upstream — see the named-tunnel section above). Ask the user which port the dashboard's Public Hostname points at, then probe `127.0.0.1:<that port>`.
+   - `external`: the upstream lives behind the user's own reverse proxy, so there is no container-local port to probe — skip this check unless the user names the upstream.
+
+Then tell the user honestly and offer the fix. For the common "hand-added tunnel, no `cloudflared`" case, send something like:
+
+> This agent has a `cloudflare-quick` tunnel configured, but `cloudflared` was never installed into the image — it's opt-in (`docker.file.cloudflared`, default `false`), and this tunnel was hand-added to `typeclaw.json` without enabling it. Want me to set `docker.file.cloudflared: true`? It's a boot setting, so after I edit it you'll run `typeclaw restart` from the host project directory, and the tunnel URL will come up.
+
+Only after the user agrees: edit `typeclaw.json` (use the `typeclaw-config` skill), ask them to `typeclaw restart` from the **host** stage, and confirm the URL once the rebuilt container is back. Never `curl`/vendor `cloudflared` yourself.
+
+### If `typeclaw tunnel status/list/logs` prints `✖ [object ErrorEvent]`
+
+On older containers the in-container CLI couldn't reach the agent websocket (it resolved the port/token via `docker`, which isn't on `$PATH` inside the container), so these commands failed at the handshake with the opaque line `✖ [object ErrorEvent]`. **That is a CLI-reachability quirk, not a tunnel outage** — do not report it to the user as "the tunnel is down" or "I can't get the URL." Fall back to the direct diagnosis above (read `typeclaw.json`, `command -v cloudflared`, probe the upstream). Current containers resolve the websocket from the in-container `TYPECLAW_*` env instead, so `tunnel status` works in-container and prints a real `detail` line; if you still see `[object ErrorEvent]`, the agent is running an older build and the direct checks are authoritative.
+
 ## Common failure modes
 
 ### `cloudflared` is not installed