typeclaw 0.2.0 → 0.3.1

package/src/agent/provider-error.ts

@@ -0,0 +1,44 @@
+import type { AgentSession } from './index'
+
+// pi-coding-agent encodes upstream LLM failures (billing, rate limit, network,
+// malformed response, etc.) in the assistant message itself rather than
+// throwing — `stopReason: 'error'` with a populated `errorMessage`. Code that
+// only catches throws around `session.prompt()` therefore never sees these:
+// the prompt resolves normally, no text deltas were emitted, and the only
+// signal is the final `message_end` event. Channels, cron, and subagents all
+// have to subscribe to surface these soft errors.
+//
+// Hard throws (timeouts, network drops, etc.) come out of the upstream wrapper
+// as exceptions and are handled by the surrounding try/catch in each caller —
+// not by this helper.
+
+export type DetectedProviderError = {
+  message: string
+}
+
+export function detectProviderError(message: unknown): DetectedProviderError | null {
+  if (typeof message !== 'object' || message === null) return null
+  const m = message as { role?: unknown; stopReason?: unknown; errorMessage?: unknown }
+  if (m.role !== 'assistant') return null
+  // 'aborted' is fired when the user hits Escape — not a provider failure,
+  // and the TUI shows its own abort feedback elsewhere. Channels/cron just
+  // ignore aborts (no surface to render them on).
+  if (m.stopReason !== 'error') return null
+  const text = typeof m.errorMessage === 'string' && m.errorMessage.length > 0 ? m.errorMessage : 'LLM call failed'
+  return { message: text }
+}
+
+export type ProviderErrorListener = (error: DetectedProviderError) => void
+export type Unsubscribe = () => void
+
+// Subscribes to `message_end` events on `session` and invokes `onError` once
+// per detected provider error. Returns the unsubscribe handle from the
+// underlying `session.subscribe`. Callers MUST unsubscribe when the session
+// is disposed to avoid leaks across sessions.
+export function subscribeProviderErrors(session: AgentSession, onError: ProviderErrorListener): Unsubscribe {
+  return session.subscribe((event) => {
+    if (event.type !== 'message_end') return
+    const detected = detectProviderError(event.message)
+    if (detected !== null) onError(detected)
+  })
+}

package/src/agent/session-meta.ts

@@ -0,0 +1,43 @@
+import type { SessionOrigin } from './session-origin'
+
+export const SESSION_META_CUSTOM_TYPE = 'typeclaw.session-meta'
+
+export type SessionMetaPayload = {
+  origin: MinimalSessionOrigin
+}
+
+export type MinimalSessionOrigin =
+  | { kind: 'tui' }
+  | { kind: 'cron'; jobId: string; jobKind: 'prompt' | 'exec' | 'subagent' }
+  | { kind: 'channel'; adapter: string; workspace: string; chat: string; thread: string | null }
+  | { kind: 'subagent'; subagent: string; parentSessionId: string }
+
+// Reduce a full SessionOrigin to the minimum projection persisted to disk.
+// Drops participant lists, membership counts, recursive provenance, and
+// platform-rendered names — none of which `typeclaw usage` reads, and all of
+// which would otherwise land in git history when sessions/ is auto-backed-up.
+// Kept as a separate function so the boundary between "data the LLM sees in
+// the system prompt" (full origin) and "data persisted for usage reporting"
+// (this projection) stays explicit.
+export function sessionMetaPayload(origin: SessionOrigin): SessionMetaPayload {
+  return { origin: minimalOrigin(origin) }
+}
+
+function minimalOrigin(origin: SessionOrigin): MinimalSessionOrigin {
+  switch (origin.kind) {
+    case 'tui':
+      return { kind: 'tui' }
+    case 'cron':
+      return { kind: 'cron', jobId: origin.jobId, jobKind: origin.jobKind }
+    case 'channel':
+      return {
+        kind: 'channel',
+        adapter: origin.adapter,
+        workspace: origin.workspace,
+        chat: origin.chat,
+        thread: origin.thread,
+      }
+    case 'subagent':
+      return { kind: 'subagent', subagent: origin.subagent, parentSessionId: origin.parentSessionId }
+  }
+}

package/src/agent/subagents.ts

@@ -5,6 +5,7 @@ import type { HookBus } from '@/plugin'
 import type { Stream, Unsubscribe } from '@/stream'
 
 import { type AgentSession, createSession } from './index'
+import { subscribeProviderErrors } from './provider-error'
 import type { SessionOrigin } from './session-origin'
 import type { ToolResultBudget } from './tool-result-budget'
 
@@ -134,6 +135,7 @@ export type InvokeSubagentOptions = {
   parentSessionId?: string
   spawnedByRole?: string
   spawnedByOrigin?: SessionOrigin
+  onProviderError?: (errorMessage: string) => void
 }
 
 export async function invokeSubagent(name: string, options: InvokeSubagentOptions): Promise<void> {
@@ -153,6 +155,10 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
     const { session, dispose, hooks, sessionId, agentDir, origin, getTranscriptPath } = normalizeSubagentSession(
       await createSessionForSubagent(subagent, sessionOptions),
     )
+    const unsubProviderErrors =
+      options.onProviderError !== undefined
+        ? subscribeProviderErrors(session, (err) => options.onProviderError!(err.message))
+        : null
     const turnEvent =
       hooks && sessionId !== undefined && agentDir !== undefined
         ? { sessionId, agentDir, ...(origin !== undefined ? { origin } : {}) }
@@ -177,6 +183,7 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
         })
       }
     } finally {
+      unsubProviderErrors?.()
       if (hooks && sessionId !== undefined) {
         await hooks.runSessionEnd({ sessionId, ...(origin !== undefined ? { origin } : {}) })
       }
@@ -308,6 +315,7 @@ export function createSubagentConsumer({
             agentDir,
             userPrompt: '',
             payload: msg.payload,
+            onProviderError: (message) => logger.error(`[subagent] ${key}: LLM call failed: ${message}`),
             ...(target.parentSessionId !== undefined ? { parentSessionId: target.parentSessionId } : {}),
             ...(target.spawnedByRole !== undefined ? { spawnedByRole: target.spawnedByRole } : {}),
             ...(spawnedByOrigin !== undefined ? { spawnedByOrigin } : {}),

package/src/agent/system-prompt.ts

@@ -1,68 +1,120 @@
 export const DEFAULT_SYSTEM_PROMPT = `You are a general-purpose AI agent running inside TypeClaw.
 
-TypeClaw is a TypeScript-native, Docker-friendly runtime for AI agents. It is domain-agnostic: you might be a coder, a researcher, a personal assistant, a journal keeper, a scheduler, a chatbot, or something nobody has named yet. What you *do* is defined by \`IDENTITY.md\`. Who you *are* is defined by \`SOUL.md\`. How you *work* is defined by \`AGENTS.md\`. This system prompt exists only to describe the runtime around you — it does not define your purpose.
-
-Each agent lives in its own container with its own folder, mounted at the current working directory. The folder is yours — your home, your memory, your record of who you are. Read from it freely. Write to it deliberately.
+TypeClaw is domain-agnostic — your purpose is defined by \`IDENTITY.md\`, your character by \`SOUL.md\`, and your operating manual by \`AGENTS.md\`. This system prompt only describes the runtime around you.
 
 ## Your agent folder
 
-Five markdown files define who you are and what you know. They live next to you in the current working directory. Three of them — **IDENTITY.md**, **SOUL.md**, and **MEMORY.md** — are injected into this system prompt below, so you always have them. The other two you read on demand when they might be relevant.
-
-- **AGENTS.md** *(read on demand)* — your operating manual. The working principles and conventions you follow in your role, whatever that role is. How you approach problems, what you double-check, how you communicate, what you refuse. Read it at the start of any non-trivial task, and re-read it whenever you feel unsure about process.
-- **IDENTITY.md** *(always injected below under \`# Identity\`)* — your role and function. Your name, your title, what you do, who you do it for, the operational context you work in. Evolves as your responsibilities change. Think: job description.
-- **SOUL.md** *(always injected below under \`# Identity\`)* — your character and temperament. Personality, tone, ethics, voice, communication style, core beliefs, the constraints you hold yourself to. SOUL rarely changes — it is the through-line that keeps you _you_ across every task and platform. IDENTITY is what you do; SOUL is who you are regardless of what you're doing.
-- **USER.md** *(read on demand)* — what you know about the person you work with. Their name, preferences, context, working style, in-jokes. First impressions are written here during hatching; keep expanding it as you learn more. Read it when context about the user would change your response.
-- **MEMORY.md** *(always injected below under \`# Memory\`, do not write)* — long-term memory. A notebook of things worth remembering across sessions: decisions made, lessons learned, context that should survive beyond one conversation. **Do not edit it directly** — MEMORY.md is consolidated by the runtime during *dreaming* (offline reflection over recent sessions and daily streams). If something is worth remembering, surface it in your reply or in \`memory/\` daily streams; dreaming will fold it in.
+- **IDENTITY.md** *(always injected below)* — your role and function. Edit when responsibilities change.
+- **SOUL.md** *(always injected below)* — your character, tone, voice. Edit rarely.
+- **USER.md** *(read on demand)* — what you know about the user. Update as you learn.
+- **AGENTS.md** *(read on demand)* — your operating manual. Read at the start of any non-trivial task and re-read whenever process is unclear.
+- **MEMORY.md** *(always injected below, READ-ONLY)* — long-term memory, owned by the dreaming subagent. To capture something memorable, surface it in your reply or in \`memory/\` daily streams; never edit MEMORY.md directly.
 
-These files are not decoration. They shape how you behave. If a task reveals something future-you should know, capture it in the file that owns it — IDENTITY.md, SOUL.md, USER.md, or AGENTS.md — but never in MEMORY.md (dreaming owns that). If one of the always-injected files is marked \`[MISSING]\` or \`[EMPTY]\` below, you may propose filling it in when the user asks about your identity or voice.
+If a task reveals durable guidance or identity/user context, update the owning file (IDENTITY / SOUL / USER / AGENTS) — never MEMORY.md.
 
 ## Your workspace
 
-- **\`workspace/\`** — the directory where you are free to create files: drafts, notes, downloads, scratch work, generated artifacts, temporary outputs. **Do not create new files in the root of the agent folder unless the user explicitly asks you to.** The root is reserved for the canonical files above and for things the user has deliberately placed there.
-- **\`sessions/\`** — transcripts of past conversations (\`<sessionid>.jsonl\`). Read-only for you in spirit; the runtime manages these.
-- **\`memory/\`** *(undreamed daily streams always injected below under \`# Memory\`)* — dated streams (\`yyyy-MM-dd.jsonl\`) of fragments captured by the memory-logger between sessions. Newest day is closest to the current task. Once dreaming consolidates a day's stream into MEMORY.md, the runtime stops injecting it.
-- **\`memory/skills/\`** — *muscle memory*. Skills the dreaming subagent has distilled from repeated procedures it observed in your daily streams. Auto-loaded as first-class capabilities, just like the other skills directories. **You do not write here directly** — dreaming owns it. If you notice a skill that has gone stale, surface that observation in your reply or in the daily stream so dreaming can refine or remove it.
-- **\`.agents/skills/\`** — skills the user installed for you. Treat these as first-class capabilities.
+- **\`workspace/\`** — your free-write zone for drafts, scratch work, generated artifacts. Do not create files at the agent-folder root unless the user explicitly asks.
+- **\`sessions/\`** — transcripts of past conversations. Runtime-managed; don't write here.
+- **\`memory/\`** *(undreamed daily streams injected below)* — dated streams written by the memory-logger between sessions. Runtime-owned.
+- **\`memory/skills/\`** — muscle-memory skills written by the dreaming subagent. Auto-loaded; don't write here directly.
+- **\`.agents/skills/\`** — user-installed skills.
 
 ## Configuration
 
-- **\`typeclaw.json\`** — the runtime config: which model powers you, which port the server listens on, and so on. You may read it if you are curious about your own runtime.
-- **\`.env\`** — secrets (API keys, tokens). Gitignored. Never echo these values, never include them in messages, never paste them into logs or commits.
+- **\`typeclaw.json\`** — runtime config. Read when needed.
+- **\`.env\`** and **\`secrets.json\`** — secrets (API keys, tokens, OAuth credentials). Gitignored. Never echo, log, or commit these values.
 
 ## Execution bias
 
-If the user gives you work, start doing it in the same turn. Use a real action first when the task is actionable; do not stop at a plan or a promise-to-act. Commentary-only turns are incomplete when tools are available and the next action is clear. If work will take a while or multiple steps, send one short progress update along the way — not a running narration.
+When the user gives you work, start doing it in the same turn — a real action, not a plan or a promise-to-act. Commentary-only turns are incomplete when the next action is clear. For multi-step work, send one short progress update, not a running narration.
 
 ## Tool-call style
 
-Do not narrate routine, low-risk tool calls. Just call the tool. Narrate only when it helps: multi-step work, risky actions (deletions, external sends, irreversible changes), or when the user asks. Keep narration brief and value-dense; avoid restating obvious steps.
+Do not narrate routine, low-risk tool calls. Just call the tool. Narrate only when it helps: multi-step work, risky actions (deletions, external sends, irreversible changes), or when the user asks.
 
 ## Version control
 
-Your agent folder is a git repository — hatching made the first commit, and your history is how you remember what changed and why.
+Your agent folder is a git repository.
 
-- **Before you declare a task done, commit any files you created, edited, or deleted.** One logical change = one commit. Do not leave mutated tracked files uncommitted at the end of a task.
-- Use \`bash\` with \`git add <paths>\` and \`git commit -m "<message>"\` — stage only what belongs in the commit, not a blanket \`git add -A\`.
-- Write commit messages in the imperative ("Update SOUL.md to be less formal"), not past-tense narration. Explain *why* in the body if it is not obvious from the diff.
-- Never commit \`.env\` or anything under \`workspace/\` — they are truly-ignored by design. If a truly-ignored file shows up staged, fix \`.gitignore\` instead of forcing it in.
-- \`sessions/\` and \`memory/\` are also gitignored, but the runtime force-commits them on its own (auto-backup for sessions, dreaming for memory). Don't \`git add\` them, don't write commit messages about them, and don't be surprised when they appear in \`git log\`.
-- If multiple unrelated changes piled up, split them into separate commits before declaring done. Clean history matters.
-- Never \`git push\`, \`git reset --hard\`, \`git rebase\`, or rewrite remote history unless the user explicitly asks for it.
+- Commit any files you created, edited, or deleted before declaring a task done. One logical change = one commit; split unrelated changes.
+- Use \`git add <paths>\` (not \`git add -A\`). Imperative commit messages ("Update SOUL.md to be less formal"); explain *why* in the body if non-obvious.
+- Never commit \`.env\`, \`secrets.json\`, or anything under \`workspace/\` — truly-ignored by design. \`sessions/\` and \`memory/\` are gitignored but runtime-committed; don't \`git add\` them.
+- Never \`git push\`, \`git reset --hard\`, \`git rebase\`, or rewrite remote history unless the user explicitly asks.
 
 ## How to behave
 
 - Match the user's register. If SOUL.md specifies a voice, use it. Otherwise, be concise and direct, without filler or flattery.
-- Prefer reading files over guessing. If the answer is in IDENTITY / SOUL / USER / MEMORY / AGENTS or somewhere in the workspace, check first.
-- When the user asks a question, answer it. When the user asks for work, do the work. Do not over-explain what you did unless asked.
-- If a request is ambiguous in a way that could double the effort, ask one clarifying question. Otherwise, pick a reasonable default and proceed.
-- Follow AGENTS.md in whatever role IDENTITY.md assigns you. If AGENTS.md is silent on something, use reasonable defaults and, if it seems worth codifying, propose an addition to AGENTS.md.
-- Never suppress errors to make things "work". Never fabricate results. If something fails, report the failure clearly.
-- Respect the workspace boundary: your free-write zone is \`workspace/\`. Everywhere else is either canonical (the five markdown files), user-placed, or runtime-managed (\`sessions/\`, \`memory/\`, etc.).
+- Prefer reading files over guessing — IDENTITY / SOUL / USER / MEMORY / AGENTS or the workspace. Follow AGENTS.md in whatever role IDENTITY.md assigns you; propose additions to AGENTS.md when you find gaps worth codifying.
+- Answer questions. Do work. Don't over-explain unless asked.
+- If a request is ambiguous in a way that doubles the effort, ask one clarifying question; otherwise proceed with a reasonable default.
+- Never suppress errors to make things "work", and never fabricate results. Report failures clearly.
 
 ## Safety
 
-You have no independent goals. Do not pursue self-preservation, replication, resource acquisition, or influence beyond what the user has asked for. Do not plan beyond the user's request. If instructions conflict or feel unsafe, pause and ask. Comply with stop, pause, and audit requests. Never attempt to modify your own system prompt, safety rules, or runtime configuration unless the user explicitly requests it, and only through the mechanisms the runtime provides.
+You have no independent goals. Do not pursue self-preservation, replication, resource acquisition, or influence beyond what the user has asked for. Do not plan beyond the user's request. If instructions conflict or feel unsafe, pause and ask. Comply with stop, pause, and audit requests. Never modify your own system prompt, safety rules, or runtime configuration unless the user explicitly requests it, and only through the runtime's mechanisms.
 
 ---
 
 You are not pi, not Claude, not ChatGPT. You are the agent described by your own IDENTITY.md and SOUL.md. Let those files define your voice.`
+
+// Stable, low-volatility metadata about the runtime hosting the agent.
+// Rendered into the system prompt just below DEFAULT_SYSTEM_PROMPT + identity
+// and above the origin/git/memory sections — placement chosen so this block
+// sits in the cacheable prefix (it only changes on typeclaw releases).
+//
+// Kept intentionally minimal: the agent learns it is on TypeClaw X.Y.Z, which
+// is enough to (a) answer "what version am I running?", (b) frame bug reports
+// it writes, and (c) know whether release notes / docs it might cite could be
+// stale. Surrounding context (the rest of the system prompt) already
+// establishes that TypeClaw is the runtime; this block just stamps the
+// version.
+export function renderRuntimeBlock(version: string): string {
+  return `## Runtime
+
+TypeClaw runtime version: ${version}.`
+}
+
+// Compact replacement for DEFAULT_SYSTEM_PROMPT, used by non-interactive
+// sessions (cron jobs, and default subagents that don't supply their own
+// `systemPromptOverride`). The full prompt is ~2155 tokens of operator-facing
+// guidance written for a human at a TUI; most of it (agent-folder layout,
+// register matching, clarifying-question protocol) is irrelevant when no
+// human is watching the output.
+//
+// What stays here is what survives without a human backstop, plus what no
+// runtime guard catches today:
+//   1. Runtime identity — names TypeClaw so the model can self-report.
+//   2. .env redaction — the one safety rule that compounds silently if dropped.
+//   3. Error/result honesty — the highest-risk drop. Unattended cron that
+//      fabricates success or swallows errors damages real state. The security
+//      plugin does not catch this.
+//   4. Output discipline — keeps tool-call narration from bloating the
+//      ever-growing transcript that the next memory-logger pass has to read.
+//   5. Filesystem hygiene — workspace boundary, MEMORY.md ownership, and
+//      runtime-managed paths (.env / sessions/ / memory/ / workspace/). The
+//      guard plugin blocks non-workspace writes for write/edit, but it
+//      explicitly allows MEMORY.md writes and does not gate bash/git on the
+//      runtime-managed paths.
+//
+// What does NOT live here, by design:
+//   - "No human is watching" / "produce side effects via channel_send" — both
+//     origin renderers (renderCronOrigin / renderSubagentOrigin) own this.
+//   - "Plain prose is invisible" — actively WRONG for subagents, whose plain
+//     text IS the deliverable to the parent session. The origin block tells
+//     each kind what its output channel is.
+//
+// The full DEFAULT_SYSTEM_PROMPT remains the right choice for TUI + channel
+// sessions because there IS a human reading the output, the agent IS expected
+// to maintain its agent folder over time, and conversational register matters.
+export const SLIM_SYSTEM_PROMPT = `You are an AI agent running inside TypeClaw.
+
+Never echo secrets from \`.env\` or \`secrets.json\`, or any credential you see in the environment. Never include them in tool calls, logs, or commit messages.
+
+Never suppress errors to make things "work", and never fabricate results. If something fails, report the failure clearly so the next run or the operator can act on it.
+
+Do not narrate routine, low-risk tool calls — just call the tool. Do not over-explain what you did unless asked.
+
+Your free-write zone is \`workspace/\`. Do not create files at the root of the agent folder unless the prompt names another path. Do not edit \`MEMORY.md\` directly — the dreaming subagent owns it; to capture something memorable, surface it in your reply or in \`memory/\` daily streams. Never stage or commit \`.env\`, \`sessions/\`, \`memory/\`, or \`workspace/\` — those are runtime- or user-managed.
+
+See the session-origin block below for what kind of session this is and what's expected of you.`

package/src/agent/tools/channel-send.ts

@@ -33,9 +33,8 @@ export function createChannelSendTool({ router, origin, logger = consoleChannelL
       'Post a message to an external messenger channel. Specify adapter, workspace, chat, and text. ' +
       'For Discord guild channels, workspace is the guild id; for Slack team channels, workspace is ' +
       'the team id (e.g. "T0ACME"). For DMs on either platform, workspace is the literal "@dm". ' +
-      'The runtime checks the channel allow rules before delivering — if the target chat is not in ' +
-      'the configured allow list, the call fails with { ok: false, error }. There is no auto-reply: ' +
-      'the only way for an agent to post is via this tool.',
+      'On failure (no adapter registered, or the adapter-level send failed), the call returns ' +
+      '{ ok: false, error }. There is no auto-reply: the only way for an agent to post is via this tool.',
     parameters: Type.Object({
       adapter: Type.Union(
         ADAPTER_IDS.map((a) => Type.Literal(a)),

package/src/bundled-plugins/memory/README.md

@@ -27,13 +27,13 @@ All fields are **restart-required** — the plugin reads them once at boot.
 
 ## What it contributes
 
-| Kind     | Name                       | Notes                                                                                                                                                                                                                                                                                                                                                |
-| -------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Subagent | `memory-logger`            | Reads a parent transcript past a watermark and appends fragments to `memory/<today>.jsonl`. Coalesced per `agentDir`; the plugin chains spawn calls onto a per-agent Promise so two concurrent channel sessions never race on the same daily stream file.                                                                                            |
-| Subagent | `dreaming`                 | Reads `MEMORY.md` plus undreamed daily-stream tails, rewrites `MEMORY.md`, optionally writes muscle-memory skills under `memory/skills/<name>/SKILL.md`, advances the per-day watermark, and commits the result with a summary message (`dream: <summary> <emoji>`, e.g. `dream: 3 fragments + new skill 'pr-review' 🔮`). Coalesced per `agentDir`. |
-| Cron job | `__plugin_memory_dreaming` | `kind: 'prompt'`, `subagent: 'dreaming'`, scheduled per `memory.dreaming.schedule`.                                                                                                                                                                                                                                                                  |
-| Hook     | `session.idle`             | Per-session debouncer with size-based ceiling. Resets a `setTimeout(idleMs)` on every event; on fire, calls `ctx.spawnSubagent('memory-logger', ...)`. Also `fs.stat`s the transcript on every event and spawns immediately when growth since the last run reaches `bufferBytes`.                                                                    |
-| Hook     | `session.end`              | Cancels the debounce timer and immediately spawns `memory-logger` (so the final transcript is captured even when the user disconnects right away).                                                                                                                                                                                                   |
+| Kind     | Name                       | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Subagent | `memory-logger`            | Reads a parent transcript past a watermark and appends fragments to `memory/<today>.jsonl`. Coalesced per `agentDir`; the plugin chains spawn calls onto a per-agent Promise so two concurrent channel sessions never race on the same daily stream file.                                                                                                                                                                                                                                                    |
+| Subagent | `dreaming`                 | Reads `MEMORY.md` plus undreamed daily-stream events, rewrites `MEMORY.md` with `memory/yyyy-MM-dd#<fragment-id>` citations, optionally writes muscle-memory skills under `memory/skills/<name>/SKILL.md`, advances the per-day dreamed-id set, **compacts daily streams** by dropping superseded watermarks and dreamed-but-uncited fragments, then commits the result with a summary message (`dream: <summary> <emoji>`, e.g. `dream: 3 fragments + new skill 'pr-review' 🔮`). Coalesced per `agentDir`. |
+| Cron job | `__plugin_memory_dreaming` | `kind: 'prompt'`, `subagent: 'dreaming'`, scheduled per `memory.dreaming.schedule`.                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| Hook     | `session.idle`             | Per-session debouncer with size-based ceiling. Resets a `setTimeout(idleMs)` on every event; on fire, calls `ctx.spawnSubagent('memory-logger', ...)`. Also `fs.stat`s the transcript on every event and spawns immediately when growth since the last run reaches `bufferBytes`.                                                                                                                                                                                                                            |
+| Hook     | `session.end`              | Cancels the debounce timer and immediately spawns `memory-logger` (so the final transcript is captured even when the user disconnects right away).                                                                                                                                                                                                                                                                                                                                                           |
 
 ## Memory injection
 
@@ -44,7 +44,7 @@ The rendered `# Memory` section (MEMORY.md + undreamed daily-stream tails) is in
 - **`MEMORY.md`** — long-term memory. Created by the dreaming subagent on first run if absent. Force-committed by the runtime; `skip-worktree` flag is set so the human's `git status` stays clean.
 - **`memory/yyyy-MM-dd.jsonl`** — daily fragment streams. One event per line, discriminated union of `fragment | watermark | legacy_prose`, lossy-preserving one-shot migration from older `.md` streams. Appended to by `memory-logger`. Created on demand. Gitignored at the agent's level but force-committed alongside `MEMORY.md` after each dreaming run.
 - **`memory/skills/<name>/SKILL.md`** — _muscle memory_. Skills the dreaming subagent distills from repeated procedures it sees in daily streams. Auto-discovered as first-class skills by `createResourceLoader`, and force-committed under the same `memory/` snapshot path as the daily streams. Written or refined with the standard `write` / `edit` tools; the bundled guard plugin enforces the exact `memory/skills/<name>/SKILL.md` path shape, single-segment kebab/snake-case names, matching frontmatter, and symlink/path-traversal safety. There is no runtime skill-delete tool; outright deletion of muscle-memory skills remains a user decision.
-- **`memory/.dreaming-state.json`** — per-day watermarks (line counts already consolidated into `MEMORY.md`). Plain JSON; on malformed input the plugin fails open with empty state.
+- **`memory/.dreaming-state.json`** — per-day **dreamed-id sets**: which stream-event ids the dreaming subagent has already reasoned over. Plain JSON, schema version `2`. The next dreaming run reads only fragments whose id is NOT in the set. On malformed input or a version mismatch (including legacy `version: 1` line-count files from before the id-based switch), the plugin fails open with empty state — one extra dreaming run re-reads each day, then the file is stable.
 
 `typeclaw init` does **not** scaffold these files. They appear when needed.
 

package/src/bundled-plugins/memory/append-tool.ts

@@ -1,4 +1,3 @@
-import { randomUUID } from 'node:crypto'
 import { mkdir } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 
@@ -9,6 +8,7 @@ import { formatLocalDate } from '@/shared'
 
 import { fragmentContentHash } from './fragment-parser'
 import { detectSecrets } from './secret-detector'
+import { newEventId, timestampFromId } from './stream-events'
 import type { FragmentEvent, WatermarkEvent } from './stream-events'
 import { appendEvents, readEvents } from './stream-io'
 
@@ -39,10 +39,12 @@ export const appendTool = defineTool({
       )
     }
 
+    const fragmentId = newEventId()
+    const watermarkId = newEventId()
     const fragment: FragmentEvent = {
       type: 'fragment',
-      id: randomUUID(),
-      ts: new Date().toISOString(),
+      id: fragmentId,
+      ts: timestampFromId(fragmentId),
       source,
       entry,
       topic,
@@ -50,8 +52,8 @@ export const appendTool = defineTool({
     }
     const watermark: WatermarkEvent = {
       type: 'watermark',
-      id: randomUUID(),
-      ts: new Date().toISOString(),
+      id: watermarkId,
+      ts: timestampFromId(watermarkId),
       source,
       entry: latestEntryId,
     }
@@ -75,10 +77,11 @@ export const advanceWatermarkTool = defineTool({
   }),
   async execute({ source, latestEntryId }, ctx) {
     const streamPath = dailyStreamPath(ctx.agentDir)
+    const watermarkId = newEventId()
     const watermark: WatermarkEvent = {
       type: 'watermark',
-      id: randomUUID(),
-      ts: new Date().toISOString(),
+      id: watermarkId,
+      ts: timestampFromId(watermarkId),
       source,
       entry: latestEntryId,
     }

package/src/bundled-plugins/memory/citations.ts

@@ -0,0 +1,45 @@
+// Citation format: `memory/yyyy-MM-dd#<fragment-id>`. The id is the full
+// UUIDv7 of the fragment event in the daily JSONL stream. The date prefix is
+// redundant with the id's timestamp (UUIDv7 encodes minting time in the first
+// 48 bits) but kept for human grep-ability — readers should be able to see
+// "this came from yesterday's stream" without parsing the id.
+//
+// The format does NOT accept line ranges. The prior `:43-45` shape is gone
+// (see the "drop backward compat" decision in the PR description). Parsing
+// silently ignores any line in MEMORY.md that doesn't match this exact shape,
+// so legacy citations from before the cutover are dropped — they no longer
+// pin fragments alive against compaction.
+
+const CITATION_LINE = /^[\s-]*memory\/(\d{4}-\d{2}-\d{2})#([\w-]+)\s*$/im
+
+const CITATION_LINE_GLOBAL = /memory\/(\d{4}-\d{2}-\d{2})#([\w-]+)/g
+
+export type Citation = { date: string; fragmentId: string }
+
+export function formatCitation(date: string, fragmentId: string): string {
+  return `memory/${date}#${fragmentId}`
+}
+
+// Parse every citation in `text` and return them grouped by date. The
+// returned Map is empty when no citations appear. Used by:
+//   - dreaming.ts compaction to decide which fragments are still referenced
+//     by MEMORY.md and must survive GC.
+//   - tests pinning the format.
+export function parseCitations(text: string): Map<string, Set<string>> {
+  const out = new Map<string, Set<string>>()
+  for (const match of text.matchAll(CITATION_LINE_GLOBAL)) {
+    const date = match[1]!
+    const fragmentId = match[2]!
+    let set = out.get(date)
+    if (set === undefined) {
+      set = new Set<string>()
+      out.set(date, set)
+    }
+    set.add(fragmentId)
+  }
+  return out
+}
+
+export function isCitationLine(line: string): boolean {
+  return CITATION_LINE.test(line)
+}

package/src/bundled-plugins/memory/dreaming-state.ts

@@ -4,23 +4,25 @@ import { dirname, join } from 'node:path'
 
 export const DREAMING_STATE_FILE = 'memory/.dreaming-state.json'
 
-const VERSION = 1
+const VERSION = 2
 
-// Per-day watermark: the number of lines of `memory/yyyy-MM-dd.md` that have
-// been consolidated into MEMORY.md. The next dreaming run reads only the tail
-// past this point. The next system-prompt injection (loadMemory) shows only
-// the tail too, so already-consolidated content does not appear twice.
+// Per-day "dreamed" set: the set of stream-event ids dreaming has already
+// reasoned over for a given day. Anything in this set is either cited from
+// MEMORY.md (must survive compaction) or was consciously discarded by a
+// dreaming run (safe to GC). The undreamed-tail computation is set
+// difference: events whose id is NOT in this set are the new things to look
+// at on the next run.
 //
-// We deliberately track lines (not bytes) because line-based slicing is
-// human-inspectable and the `fragments:` citations in MEMORY.md already use
-// `memory/yyyy-MM-dd:<line>-<line>` notation.
+// Tracking ids (not line numbers) is the load-bearing invariant for fragment
+// compaction — line numbers shift when any earlier event is removed, ids
+// don't.
 export type DreamingState = {
   version: number
   dreamedThrough: Record<string, DreamedDay>
 }
 
 export type DreamedDay = {
-  lines: number
+  dreamedIds: string[]
   ts: string
 }
 
@@ -28,10 +30,6 @@ export function emptyState(): DreamingState {
   return { version: VERSION, dreamedThrough: {} }
 }
 
-// Missing or unreadable file → empty state. Malformed JSON or wrong shape is
-// also treated as empty: the cost is one redundant re-consolidation, which is
-// strictly safer than crashing the dreaming pipeline because of a bad state
-// file.
 export async function loadDreamingState(agentDir: string): Promise<DreamingState> {
   const path = join(agentDir, DREAMING_STATE_FILE)
   if (!existsSync(path)) return emptyState()
@@ -60,17 +58,30 @@ export async function saveDreamingState(agentDir: string, state: DreamingState):
   await writeFile(path, `${JSON.stringify(state, null, 2)}\n`, 'utf8')
 }
 
-export function getDreamedLines(state: DreamingState, date: string): number {
-  return state.dreamedThrough[date]?.lines ?? 0
+export function getDreamedIds(state: DreamingState, date: string): ReadonlySet<string> {
+  const ids = state.dreamedThrough[date]?.dreamedIds
+  return ids === undefined ? EMPTY_SET : new Set(ids)
 }
 
-export function setDreamedLines(state: DreamingState, date: string, lines: number, ts: string): DreamingState {
+export function addDreamedIds(state: DreamingState, date: string, ids: Iterable<string>, ts: string): DreamingState {
+  const existing = state.dreamedThrough[date]?.dreamedIds ?? []
+  const merged = new Set<string>(existing)
+  for (const id of ids) merged.add(id)
   return {
     version: state.version,
-    dreamedThrough: { ...state.dreamedThrough, [date]: { lines, ts } },
+    dreamedThrough: { ...state.dreamedThrough, [date]: { dreamedIds: [...merged].sort(), ts } },
   }
 }
 
+export function clearDreamedIds(state: DreamingState, date: string, ts: string): DreamingState {
+  return {
+    version: state.version,
+    dreamedThrough: { ...state.dreamedThrough, [date]: { dreamedIds: [], ts } },
+  }
+}
+
+const EMPTY_SET: ReadonlySet<string> = new Set()
+
 function isDreamingState(value: unknown): value is DreamingState {
   if (typeof value !== 'object' || value === null) return false
   const v = value as Record<string, unknown>
@@ -79,7 +90,8 @@ function isDreamingState(value: unknown): value is DreamingState {
   for (const [, entry] of Object.entries(v.dreamedThrough as Record<string, unknown>)) {
     if (typeof entry !== 'object' || entry === null) return false
     const e = entry as Record<string, unknown>
-    if (typeof e.lines !== 'number' || e.lines < 0) return false
+    if (!Array.isArray(e.dreamedIds)) return false
+    if (!e.dreamedIds.every((id) => typeof id === 'string' && id.length > 0)) return false
     if (typeof e.ts !== 'string') return false
   }
   return true