typeclaw 0.2.0 → 0.3.0

package/package.json

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

package/src/agent/index.ts

@@ -30,7 +30,7 @@ import { resolveBuiltinToolRefs, wrapPluginTool, wrapSystemAgentTool, wrapSystem
 import { createReloadTool } from './reload-tool'
 import { loadSelf } from './self'
 import { renderSessionOrigin, type SessionOrigin, type SessionRoleContext } from './session-origin'
-import { DEFAULT_SYSTEM_PROMPT } from './system-prompt'
+import { DEFAULT_SYSTEM_PROMPT, renderRuntimeBlock } from './system-prompt'
 import {
   createBudgetState,
   type ToolResultBudget,
@@ -104,6 +104,13 @@ 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 typeclaw runtime version (`package.json#version` of the executing
+  // CLI) to surface in the system prompt under `## Runtime`. Threaded from
+  // `startAgent` via `CLI_VERSION` so every session — TUI, channel, cron,
+  // plugin subagent — sees the same value. Omitted in stand-alone test
+  // callers, in which case the runtime block is skipped (no token cost, no
+  // misleading "unknown" value).
+  runtimeVersion?: 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
@@ -171,11 +178,17 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
 
   const resourceLoader =
     options.systemPromptOverride !== undefined
-      ? await createOverrideResourceLoader(options.systemPromptOverride, options.origin, options.permissions)
+      ? await createOverrideResourceLoader(
+          options.systemPromptOverride,
+          options.origin,
+          options.permissions,
+          options.runtimeVersion,
+        )
       : await createResourceLoader({
           ...(options.plugins ? { plugins: options.plugins, materializedSkills } : {}),
           ...(options.origin ? { origin: options.origin } : {}),
           ...(options.permissions ? { permissions: options.permissions } : {}),
+          ...(options.runtimeVersion !== undefined ? { runtimeVersion: options.runtimeVersion } : {}),
         })
 
   const getOrigin: () => SessionOrigin | undefined =
@@ -475,8 +488,11 @@ export async function createOverrideResourceLoader(
   systemPrompt: string,
   origin?: SessionOrigin,
   permissions?: PermissionService,
+  runtimeVersion?: string,
 ): Promise<DefaultResourceLoader> {
-  const finalPrompt = withOrigin(systemPrompt, origin, permissions)
+  const withRuntime =
+    runtimeVersion !== undefined ? `${systemPrompt}\n\n${renderRuntimeBlock(runtimeVersion)}` : systemPrompt
+  const finalPrompt = withOrigin(withRuntime, origin, permissions)
   const loader = new DefaultResourceLoader({
     systemPromptOverride: () => finalPrompt,
     appendSystemPromptOverride: () => [],
@@ -491,6 +507,7 @@ export type CreateResourceLoaderOptions = {
   materializedSkills?: MaterializedSkills | null
   origin?: SessionOrigin
   permissions?: PermissionService
+  runtimeVersion?: string
 }
 
 export async function createResourceLoader(options: CreateResourceLoaderOptions = {}): Promise<DefaultResourceLoader> {
@@ -509,6 +526,7 @@ export async function createResourceLoader(options: CreateResourceLoaderOptions
   // section changes (the provider's prompt cache hits up to the first byte
   // that differs).
   //
+  // 0. runtime block — most stable: only changes on typeclaw releases (rare).
   // 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
@@ -517,6 +535,9 @@ export async function createResourceLoader(options: CreateResourceLoaderOptions
   //    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.
+  if (options.runtimeVersion !== undefined) {
+    systemPrompt = `${systemPrompt}\n\n${renderRuntimeBlock(options.runtimeVersion)}`
+  }
   systemPrompt = withOrigin(systemPrompt, options.origin, options.permissions)
 
   const gitNudge = await renderGitNudge(agentDir)

package/src/agent/system-prompt.ts

@@ -66,3 +66,20 @@ You have no independent goals. Do not pursue self-preservation, replication, res
 ---
 
 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}.`
+}

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