@xingular/harness 2.0.0 → 2.0.1-unstable

package/src/mcp/types.ts

@@ -1,118 +0,0 @@
-// Connected apps: MCP servers the user added. A connection is device-local; its secrets
-// (environment values, request headers, OAuth tokens and client) are in the secret store,
-// never in `connections.json`.
-import { z } from 'zod'
-
-/** Loopback address every OAuth sign-in returns to. Pre-registered clients must list it exactly. */
-export const MCP_OAUTH_PORT = 47823
-export const MCP_OAUTH_REDIRECT_URL = `http://127.0.0.1:${MCP_OAUTH_PORT}/oauth/callback`
-
-/**
- * The application's own registered OAuth clients, by catalog entry. A client supplied here is
- * used for that sign-in only and is never written to the connection or the secret store.
- */
-export interface AppOAuthClients {
-  /** The catalog entries this application can sign in for. */
-  ids(): string[]
-  get(catalogId: string): Promise<{ clientId: string; clientSecret?: string } | null>
-}
-
-/** Stable attachment key for a connected app's capability switch. */
-export const connectionCapabilityId = (id: string): string => `connected-apps/connection/${id}`
-
-export const connectionSchema = z.object({
-  id: z.string().default(''),
-  name: z.string().default(''),
-  /** `workspace` (the first-party Xingular Workspace server), `local` (a command), or `remote` (Streamable HTTP). */
-  kind: z.string().default(''),
-  command: z.string().default(''),
-  args: z.array(z.string()).default([]),
-  cwd: z.string().nullable().default(null),
-  envKeys: z.array(z.string()).default([]),
-  enabled: z.boolean().default(false),
-  /** Available to every agent and project, except those excluded. */
-  global: z.boolean().default(false),
-  agentIds: z.array(z.string()).default([]),
-  projectIds: z.array(z.string()).default([]),
-  excludedAgentIds: z.array(z.string()).default([]),
-  excludedProjectIds: z.array(z.string()).default([]),
-  /** Tools that run without asking. */
-  readTools: z.array(z.string()).default([]),
-  expectedVaultId: z.string().nullable().default(null),
-  checkedAt: z.string().nullable().default(null),
-  serverName: z.string().nullable().default(null),
-  tools: z.array(z.unknown()).default([]),
-  error: z.string().nullable().default(null),
-  url: z.string().nullable().default(null),
-  /** `none`, `headers`, or `oauth`. */
-  auth: z.string().default(''),
-  headerKeys: z.array(z.string()).default([]),
-  oauthClient: z.string().nullable().default(null),
-  oauthScopes: z.array(z.string()).default([]),
-  authState: z.string().nullable().default(null),
-  catalogId: z.string().nullable().default(null)
-})
-export type Connection = z.infer<typeof connectionSchema>
-
-export const connectionInputSchema = connectionSchema.extend({
-  env: z.record(z.string(), z.string()).nullish(),
-  removeEnv: z.array(z.string()).nullish(),
-  headers: z.record(z.string(), z.string()).nullish(),
-  removeHeaders: z.array(z.string()).nullish(),
-  /** A client registered by the user with the provider; replaces any saved sign-in. */
-  oauthCredentials: z.object({ clientId: z.string(), clientSecret: z.string() }).nullish()
-})
-export type ConnectionInput = z.input<typeof connectionInputSchema>
-
-export interface StdioConfig {
-  id: string
-  name: string
-  transport: 'stdio'
-  command: string
-  args: string[]
-  cwd: string | null
-  env: Record<string, string>
-}
-
-export interface HttpConfig {
-  id: string
-  name: string
-  transport: 'http'
-  url: string
-  headers: Record<string, string>
-  auth: 'none' | 'headers' | 'oauth'
-  scopes: string[]
-}
-
-/** What it takes to reach a server: a process to start, or an address and its credentials. */
-export type LaunchConfig = StdioConfig | HttpConfig
-
-/** Who a session is, for deciding which connections it may reach. */
-export interface Scope {
-  agentId?: string | null
-  projectId?: string | null
-}
-
-export interface McpSource {
-  id: string
-  title: string
-  uri: string
-  path?: string | null
-  revision?: string
-  excerpt?: string
-  projectId?: string
-}
-
-/** One connected-app call a run made, kept in `runs/<id>/mcp-context.json`. */
-export interface McpTrace {
-  id: string
-  connectionId: string
-  connectionName: string
-  tool: string
-  at: string
-  ok: boolean
-  summary: string
-  result: string
-  sources: McpSource[]
-  truncated: boolean
-}

package/src/memory/api.test.ts

@@ -1,82 +0,0 @@
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { afterEach, expect, test } from 'vitest'
-
-import { dataRoot, writeFile } from '../../tests/helpers'
-import { createEnv, type HarnessEnv } from '../core/env'
-import { writeJson } from '../core/fs'
-import { closeIndex } from '../core/index'
-import { launchText } from '../prompt/compile'
-import { list, memories, memoryEdit, propose, read, search, skill } from './api'
-import * as blocks from './blocks'
-import type { CallerContext } from './caller'
-import { findMemory } from './facts'
-import { readRunContext } from './runContext'
-import { ensureProjectNamespace, wikiDir } from './store'
-import { reindexWiki } from './wikiIndex'
-
-const roots: string[] = []
-afterEach(() => roots.splice(0).forEach(closeIndex))
-
-function setup(): HarnessEnv {
-  const root = dataRoot()
-  roots.push(root)
-  writeJson(join(root, 'projects.json'), [
-    { id: 'p1', name: 'Xingular Agent', rootPath: '/src/xingular-agent', autoMaintenance: true, createdAt: 't', slug: 'xingular-agent' },
-    { id: 'p2', name: 'Site', rootPath: '/src/site', autoMaintenance: true, createdAt: 't', slug: 'site' }
-  ])
-  ensureProjectNamespace(root, 'xingular-agent', 'Xingular Agent')
-  ensureProjectNamespace(root, 'site', 'Site')
-  const wiki = wikiDir(root)
-  writeFileSync(join(wiki, 'projects/site/deploy.md'), '---\nid: deploy\ntitle: Deploying the site\ntype: decision\nsourceIds: [run:r0]\n---\n\nThe site deploys with wrangler.\n')
-  writeFileSync(join(wiki, 'facts/pnpm.md'), '---\nid: pnpm\ntitle: Use pnpm\nkind: preference\nnamespace: /\nconfidence: high\n---\n\nUse pnpm, not npm.\n')
-  writeFileSync(join(wiki, 'facts/site-only.md'), '---\nid: site-only\ntitle: Site uses Astro\nkind: fact\nnamespace: /projects/site\n---\n\nAstro.\n')
-  writeFile(join(root, 'registry/rules/tests.md'), '---\nname: Run tests\n---\n\nAlways run the tests.\n')
-  writeFile(join(root, 'registry/skills/review/SKILL.md'), '---\nname: review\ndescription: Review a change\n---\n\nRead the diff first.\n')
-  writeJson(join(root, 'config/registry-enabled.json'), { global: ['rules/tests'], p1: ['skills/review'] })
-  mkdirSync(join(root, 'runs/run-1'), { recursive: true })
-  writeJson(join(root, 'runs/run-1/run.json'), { id: 'run-1', projectId: 'p1', mode: 'code', harness: 'pi', sessionType: 'structured', sessionId: 's1', nativeSessionId: null, workingDirectory: null, worktreeId: null, goal: 'Please keep commits small from now on.', startedAt: 't', endedAt: null, status: 'running' })
-  reindexWiki(root)
-  return createEnv(root)
-}
-
-const context = (project: string): CallerContext => ({ runId: 'run-1', projectId: project, actor: 'Code' })
-
-test('sessions edit their project brief through memory calls', () => {
-  const env = setup()
-  expect(memoryEdit(env, context('p1'), 'memory.append', { block: 'project', text: 'Tauri 2 desktop app.' })).toContain('project/xingular-agent')
-  expect(launchText(env, context('p1'))).toContain('Tauri 2 desktop app.')
-  expect(() => memoryEdit(env, context('p1'), 'memory.append', { block: 'user', text: 'x' })).toThrow()
-  // A session reads its project's brief by id, but never an agent's blocks.
-  expect(read(env, context('p1'), { id: 'blocks/projects/xingular-agent/brief' })).toContain('Tauri 2 desktop app.')
-  blocks.ensureAgent(wikiDir(env.root), 'a1')
-  expect(() => read(env, context('p1'), { id: 'blocks/agents/a1/persona' })).toThrow()
-  expect(() => memoryEdit(env, { actor: 'Chat' }, 'memory.append', { block: 'user', text: 'x' })).toThrow()
-  expect(readRunContext(env.root, 'run-1').some((entry) => entry.id === 'blocks/projects/xingular-agent/brief' && entry.via === 'edit')).toBe(true)
-})
-
-test('agents read across project namespaces', () => {
-  const env = setup()
-  const hits = search(env, context('p1'), { query: 'wrangler' })
-  expect(hits).toContain('Deploying the site')
-  expect(hits).toContain('/projects/site/deploy')
-  const page = read(env, context('p1'), { id: '/projects/site/deploy' })
-  expect(page).toContain('The site deploys with wrangler.')
-  expect(page).toContain('Sources: run:r0')
-  expect(skill(env, context('p2'), { name: 'review' })).toContain('Read the diff first.')
-  expect(memories(env, context('p1'), { namespace: '/projects/site' })).toContain('Astro')
-  expect(list(env, {})).toContain('/projects/site')
-  expect(readRunContext(env.root, 'run-1').some((entry) => entry.id === 'deploy' && entry.via === 'read')).toBe(true)
-})
-
-test('proposals apply in the project namespace or wait in the inbox', () => {
-  const env = setup()
-  const applied = propose(env, context('p1'), { kind: 'memory', title: 'Small commits', type: 'preference', body: 'Keep commits small.', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'current', excerpt: 'please keep commits small' }] })
-  expect(applied).toContain('saved')
-  expect(findMemory(wikiDir(env.root), 'small-commits').front.namespace).toBe('/projects/xingular-agent')
-  expect(propose(env, context('p1'), { kind: 'page', title: 'Rumor', body: 'Maybe.' })).toContain('Inbox')
-  // The caller's own run without a quote from it is not evidence.
-  expect(propose(env, context('p1'), { kind: 'memory', title: 'Bare', body: 'Unquoted.', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'current' }] })).toContain('Inbox')
-  expect(propose(env, context('p1'), { kind: 'skill', title: 'Deploy', body: 'Steps.' })).toContain('waiting in the Wiki Inbox')
-  expect(existsSync(join(env.root, 'registry/skills/deploy'))).toBe(false)
-})

package/src/memory/api.ts

@@ -1,303 +0,0 @@
-// The Wiki as a model sees it: search, read, list, skills, facts, proposals, and memory-block
-// edits. Results are plain text with `[id@revision]` citations, and every entry a run reads is
-// recorded in `runs/<id>/wiki-context.json`.
-import { dirname } from 'node:path'
-
-import type { HarnessEnv } from '../core/env'
-import { HarnessError, invalid, notFound } from '../core/errors'
-import { charCount } from '../core/text'
-import { applicableMemories, clip } from '../prompt/compile'
-import { findRun, readEvents } from '../sessions/runStore'
-import type { RunEvent } from '../sessions/contracts'
-import { takeChars } from '../core/text'
-import * as registry from '../skills/registry'
-import { enqueueCuration } from './curation'
-import * as blocks from './blocks'
-import { actorOf, blockCaller, projectOf, type CallerContext } from './caller'
-import * as facts from './facts'
-import { apply, captureHashes, parkRegistryProposal, parseProposalSet, type Trigger } from './proposals'
-import * as references from './references'
-import { cite, record, recordSources } from './runContext'
-import * as store from './store'
-import { backlinks, entryId, namespaces, registryEntryKind, resolveEntry, searchEntries } from './wiki'
-
-const READ_LIMIT = 20_000
-
-export type Params = Record<string, unknown> | null | undefined
-
-function textParam(params: Params, key: string): string {
-  const value = params?.[key]
-  return typeof value === 'string' ? value.trim() : ''
-}
-
-const rawParam = (params: Params, key: string): string => (typeof params?.[key] === 'string' ? (params[key] as string) : '')
-const countParam = (params: Params, key: string): number | null => {
-  const value = params?.[key]
-  return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : null
-}
-
-// ---- Run evidence -------------------------------------------------------------------------------
-
-function transcriptText(goal: string, events: readonly RunEvent[]): string {
-  let text = `User: ${goal}\n`
-  for (const event of events) {
-    const payload = event.payload as { role?: unknown; text?: unknown; name?: unknown; summary?: unknown }
-    if (event.type === 'message.completed' && payload.role === 'assistant') text += `Assistant: ${typeof payload.text === 'string' ? payload.text : ''}\n`
-    else if (event.type === 'tool.started') text += `Tool ${typeof payload.name === 'string' ? payload.name : 'tool'}: ${typeof payload.summary === 'string' ? payload.summary : ''}\n`
-  }
-  return text
-}
-
-/** What a consolidation job reads of a run, capped. */
-export function transcript(goal: string, events: readonly RunEvent[]): string {
-  return takeChars(transcriptText(goal, events), 24_000)
-}
-
-/** Everything recorded of a run, uncapped: what an excerpt is checked against. */
-export function evidenceText(root: string, runId: string): string {
-  let events: RunEvent[] = []
-  try {
-    events = readEvents(root, runId)
-  } catch {
-    events = []
-  }
-  return transcriptText(findRun(root, runId)?.goal ?? '', events)
-}
-
-// ---- Memory blocks -----------------------------------------------------------------------
-
-/** `memory.append`, `memory.replace`, and `memory.rethink`. */
-export function memoryEdit(env: HarnessEnv, context: CallerContext, call: string, params: Params): string {
-  const caller = blockCaller(env, context)
-  const label = textParam(params, 'block')
-  if (!label) throw invalid('Name the block to edit, such as user, persona, or notes.')
-  let edit: blocks.Edit
-  if (call === 'memory.append') edit = { kind: 'append', text: rawParam(params, 'text') }
-  else if (call === 'memory.replace') edit = { kind: 'replace', old: rawParam(params, 'old'), new: rawParam(params, 'new') }
-  else if (call === 'memory.rethink') edit = { kind: 'rethink', text: rawParam(params, 'body') }
-  else throw new HarnessError('unknown_method', `Unknown memory call ${call}.`)
-  const block = blocks.edit(env.root, caller, label, edit)
-  record(env.root, context, 'edit', [[block.id, 'block']])
-  return `Updated the ${block.front.label} block (${charCount(block.body)} of ${block.front.limit} characters). It is in your context from the next turn.`
-}
-
-// ---- Retrieval ------------------------------------------------------------------------------
-
-function ownBlocksPrefix(env: HarnessEnv, context: CallerContext): string | null {
-  try {
-    const caller = blockCaller(env, context)
-    return caller.kind === 'agent' ? `blocks/agents/${caller.id}/` : null
-  } catch {
-    return null
-  }
-}
-
-/** A fact is stored and indexed under the kind `memory`. A model says `fact`; `memory` is still understood. */
-const storedKind = (kind: string): string => (kind === 'fact' ? 'memory' : kind)
-const shownKind = (kind: string): string => (kind === 'memory' ? 'fact' : kind)
-
-export function search(env: HarnessEnv, context: CallerContext, params: Params): string {
-  const { root } = env
-  const query = textParam(params, 'query')
-  if (!query) return 'Give a query.'
-  const kinds = (Array.isArray(params?.kinds) ? params.kinds.filter((kind): kind is string => typeof kind === 'string') : []).map(storedKind)
-  const limit = countParam(params, 'limit') ?? 8
-  // Another agent's blocks never appear; a block of the caller's own does.
-  const own = ownBlocksPrefix(env, context)
-  const hits = searchEntries(root, query, { kinds, namespace: textParam(params, 'namespace') || null, projectId: context.projectId, limit: limit + 6 })
-    .filter((hit) => context.vaultAccess === 'curator' || !(hit.kind === 'block' && hit.type === 'agent') || (own !== null && hit.id.startsWith(own)))
-    .slice(0, limit)
-  if (!hits.length) return 'No matching Wiki entries.'
-  const wiki = store.wikiDir(root)
-  record(root, context, 'search', hits.map((hit) => [hit.id, hit.kind]))
-  return `${hits.map((hit, index) => `${index + 1}. [${shownKind(hit.kind)}] ${hit.title} — ${hit.path} ${cite(wiki, hit.id)}\n   ${hit.snippet}`).join('\n')}\n\nRead an entry with wiki_read and its id or path.`
-}
-
-export function read(env: HarnessEnv, context: CallerContext, params: Params): string {
-  const { root } = env
-  const key = textParam(params, 'id') || textParam(params, 'path') || textParam(params, 'idOrPath')
-  if (!key) throw invalid('Give an id or Wiki path.')
-  if (typeof params?.revision === 'string') {
-    const text = references.readPinned(root, context.runId, key, params.revision, countParam(params, 'offset') ?? 0)
-    recordSources(root, context, 'read', [{ id: key, kind: key.startsWith('skills/') ? 'skill' : 'page', revision: params.revision }])
-    return text
-  }
-  const wiki = store.wikiDir(root)
-  const entry = resolveEntry(root, key)
-  // An agent's own blocks are not readable by other agents or by sessions.
-  if (entry.kind === 'block' && entry.block.scope === 'agent') {
-    const own = ownBlocksPrefix(env, context)
-    if (context.vaultAccess !== 'curator' && (own === null || `blocks/agents/${entry.block.owner}/` !== own)) throw notFound('Wiki entry')
-  }
-  const linking = backlinks(root, entryId(entry))
-  const linked = linking.length ? linking.map((link) => `${link.fromId} (${link.type})`).join(', ') : 'none'
-  let kind: string
-  let text: string
-  if (entry.kind === 'page') {
-    const { frontmatter: front, location, body } = entry.page
-    kind = 'page'
-    text = `# ${front.title} ${cite(wiki, front.id)}\nPath: ${location.path} · namespace ${location.namespace} · type ${front.type} · updated ${front.updatedAt}\nSources: ${front.sourceIds.length ? front.sourceIds.join(', ') : 'none (unresolved)'}\nLinks: ${front.links.length ? front.links.map((link) => `${link.type} ${link.toId}`).join(', ') : 'none'}\nBacklinks: ${linked}\n\n${clip(body, READ_LIMIT)}`
-  } else if (entry.kind === 'memory') {
-    const { front, body } = entry.memory
-    kind = 'memory'
-    text = `# ${front.title} ${cite(wiki, front.id)}\nFact · ${front.kind} · namespace ${front.namespace} · ${front.confidence} confidence · ${front.status}${front.supersedes ? ` · supersedes ${front.supersedes}` : ''}\nSources: ${front.sourceIds.length ? front.sourceIds.join(', ') : 'none'}\nBacklinks: ${linked}\n\n${body}`
-  } else if (entry.kind === 'block') {
-    const { block } = entry
-    kind = 'block'
-    text = `# ${block.front.label} ${cite(wiki, block.id)}\nMemory block · ${block.scope} · ${charCount(block.body)} of ${block.front.limit} characters\n${block.front.description}\n\n${block.body}`
-  } else {
-    const { item } = entry
-    kind = registryEntryKind(item.kind) ?? 'skill'
-    text = `# ${item.name} ${cite(wiki, item.id)}\nRegistry ${item.id} · file ${item.path}\nBacklinks: ${linked}\n\n${clip(registry.itemBody(item), READ_LIMIT)}`
-  }
-  record(root, context, 'read', [[entryId(entry), kind]])
-  return text
-}
-
-export function list(env: HarnessEnv, params: Params): string {
-  const { root } = env
-  const namespace = textParam(params, 'namespace')
-  const kind = storedKind(textParam(params, 'kind'))
-  const wiki = store.wikiDir(root)
-  if (kind === 'memory') {
-    const memories = facts.loadMemories(wiki)
-    if (!memories.length) return 'No facts yet.'
-    return memories
-      .filter((memory) => !namespace || memory.front.namespace === namespace)
-      .map((memory) => `- ${memory.front.title} (${memory.front.id}) [${memory.front.kind}] ${memory.front.namespace} · ${memory.front.status}`)
-      .join('\n')
-  }
-  if (kind === 'skill' || kind === 'rule' || kind === 'prompt') {
-    const plural = `${kind}s`
-    const items = registry.list(root).filter((item) => item.kind === plural).map((item) => `- ${item.name} (${item.id}) — ${item.description}`)
-    return items.length ? items.join('\n') : `No ${plural} yet.`
-  }
-  let text = ''
-  if (!namespace) text += `Namespaces: / (Home), /library${namespaces(root).map((entry) => `, ${entry.namespace}`).join('')}\n\n`
-  const prefix = `${namespace.replace(/\/+$/, '')}/`
-  const pages = store
-    .loadPages(wiki)
-    .filter((page) => !namespace || page.location.namespace === namespace || page.location.path.startsWith(prefix))
-    .slice(0, 200)
-    .map((page) => `- ${page.location.path} — ${page.frontmatter.title} (${page.frontmatter.type}) [${page.frontmatter.id}]`)
-  return text + (pages.length ? pages.join('\n') : 'No pages here.')
-}
-
-/** One skill's instructions by name or id, or the skills index when no name is given. */
-export function skill(env: HarnessEnv, context: CallerContext, params: Params, contributions?: readonly string[]): string {
-  const { root } = env
-  const name = textParam(params, 'name').toLowerCase()
-  const items = registry.limitToContributions(registry.list(root).filter((item) => item.kind === 'skills'), contributions)
-  if (!name) {
-    if (!items.length) return 'No skills yet.'
-    const active = (contributions === undefined
-      ? registry.enabledFor(root, context.projectId ?? null, context.agentId ?? null)
-      : items).map((item) => item.id)
-    return items.map((item) => `- ${item.name} (${item.id})${active.includes(item.id) ? ' · active' : ''} — ${item.description}`).join('\n')
-  }
-  const found = items.find((item) => item.id.toLowerCase() === name || item.id.replace(/^skills\//, '').toLowerCase() === name || item.name.toLowerCase() === name)
-  if (!found) return `There is no skill called "${name}". Call skill_load without a name to list them.`
-  record(root, context, 'skill', [[found.id, 'skill']])
-  const folder = found.path.endsWith('SKILL.md') ? `\nSupporting files are in ${dirname(found.path)}.` : ''
-  return `# ${found.name} ${cite(store.wikiDir(root), found.id)}\n${found.description}${folder}\n\n${clip(registry.itemBody(found), READ_LIMIT)}`
-}
-
-/** ", volatile, observed 12 days ago" for a fact that describes current state. */
-export function volatileNote(front: facts.MemoryFront): string {
-  if (!front.volatile) return ''
-  const days = facts.ageDays(front)
-  return days === null ? ', volatile' : `, volatile, observed ${days} day${days === 1 ? '' : 's'} ago`
-}
-
-export function memories(env: HarnessEnv, context: CallerContext, params: Params): string {
-  const { root } = env
-  const wiki = store.wikiDir(root)
-  const query = textParam(params, 'query')
-  const namespace = textParam(params, 'namespace')
-  let selected: facts.ParsedMemory[]
-  if (!query) {
-    selected = applicableMemories(wiki, namespace || (projectOf(root, context)?.wikiNamespace ?? null))
-  } else {
-    selected = searchEntries(root, query, { kinds: ['memory'], namespace: namespace || null, projectId: context.projectId, limit: 20 }).flatMap((hit) => {
-      try {
-        return [facts.findMemory(wiki, hit.id)]
-      } catch {
-        return []
-      }
-    })
-  }
-  if (!selected.length) return 'No facts match.'
-  const shown = selected.slice(0, 30)
-  record(root, context, 'memory', shown.map((memory) => [memory.front.id, 'memory']))
-  return shown
-    .map((memory) => `- [${memory.front.kind}] ${memory.front.title} ${cite(wiki, memory.front.id)} (${memory.front.namespace}, ${memory.front.confidence} confidence${memory.front.status === 'active' ? '' : `, ${memory.front.status}`}${volatileNote(memory.front)})\n  ${memory.body.trim().replaceAll('\n', '\n  ')}`)
-    .join('\n')
-}
-
-// ---- Proposals -------------------------------------------------------------------------------
-
-function sourceRefs(params: Params, context: CallerContext): { kind: string; ref: string; excerpt?: string }[] {
-  if (!Array.isArray(params?.sourceRefs)) return []
-  return params.sourceRefs.flatMap((reference: { kind?: unknown; ref?: unknown; excerpt?: unknown } | null) => {
-    if (!reference || typeof reference.kind !== 'string') return []
-    const given = typeof reference.ref === 'string' ? reference.ref : ''
-    // "current" (or nothing) names the caller's own run.
-    const own = reference.kind === 'run' && (!given || given === 'current')
-    if (own && !context.runId) return []
-    return [{ kind: reference.kind, ref: own ? context.runId! : given, ...(typeof reference.excerpt === 'string' ? { excerpt: reference.excerpt } : {}) }]
-  })
-}
-
-/** A `links` argument: usable only when every entry names a target and a type. */
-function links(params: Params): { toId: string; type: string }[] {
-  const given = params?.links
-  if (!Array.isArray(given) || !given.every((link) => link && typeof link.toId === 'string' && typeof link.type === 'string')) return []
-  return given.map((link: { toId: string; type: string }) => ({ toId: link.toId, type: link.type }))
-}
-
-const optional = (params: Params, key: string): string | null => textParam(params, key) || null
-
-/** Validates and applies (or parks) one proposal. */
-export function propose(env: HarnessEnv, context: CallerContext, params: Params): string {
-  const { root } = env
-  const wiki = store.wikiDir(root)
-  const kind = storedKind(textParam(params, 'kind'))
-  const trigger: Trigger = { kind: 'agent', runId: context.runId ?? null, actor: actorOf(context) }
-  const defaultNamespace = projectOf(root, context)?.wikiNamespace ?? store.LIBRARY_NAMESPACE
-  const title = textParam(params, 'title')
-  const body = rawParam(params, 'body')
-  let proposals: unknown
-  if (kind === 'page') {
-    proposals = { pages: [{ id: optional(params, 'id'), title, type: optional(params, 'type') ?? 'concept', body, namespace: optional(params, 'namespace'), confidence: optional(params, 'confidence'), sourceRefs: sourceRefs(params, context), links: links(params) }] }
-  } else if (kind === 'memory') {
-    proposals = {
-      memories: [{ id: optional(params, 'id'), title, kind: optional(params, 'type') ?? 'fact', body, namespace: optional(params, 'namespace'), confidence: optional(params, 'confidence'), supersedes: optional(params, 'supersedes'), volatile: typeof params?.volatile === 'boolean' ? params.volatile : null, sourceRefs: sourceRefs(params, context), links: links(params) }]
-    }
-  } else if (kind === 'block') {
-    const id = textParam(params, 'id')
-    const block = blocks.find(wiki, id)
-    if (block.front.readOnly) throw invalid('This block is user-only; only the user can change it.')
-    proposals = { blocks: [{ block: id, body, sourceRefs: sourceRefs(params, context) }] }
-  } else if (kind === 'skill' || kind === 'rule' || kind === 'prompt') {
-    if (context.vaultAccess) {
-      const job = enqueueCuration(root, { kind: 'registry', proposal: { kind, name: optional(params, 'id') ?? title, description: textParam(params, 'description'), body, reason: textParam(params, 'reason') }, caller: context })
-      return `Submitted proposal ${job.id} for curator review. Nothing has been changed.`
-    }
-    const id = parkRegistryProposal(wiki, trigger, { kind, name: optional(params, 'id') ?? title, description: textParam(params, 'description'), body, reason: textParam(params, 'reason') })
-    return `The ${kind} change (${id}) is waiting in the Wiki Inbox. Skills, prompts, and rules change only after the user accepts them.`
-  } else {
-    throw invalid('kind must be page, fact, skill, rule, or prompt.')
-  }
-  // The caller's own run is evidence only for what it can quote from it.
-  if (context.vaultAccess) {
-    const job = enqueueCuration(root, { kind: 'proposal', namespace: defaultNamespace, proposals: parseProposalSet(proposals), caller: context })
-    return `Submitted proposal ${job.id} for curator review. Nothing has been changed.`
-  }
-  const outcome = apply(wiki, defaultNamespace, trigger, parseProposalSet(proposals), captureHashes(wiki), { runText: context.runId ? evidenceText(root, context.runId) : null })
-  let text = outcome.notes.join('\n')
-  if (outcome.operation) {
-    text += `\nApplied as operation ${outcome.operation.id.slice(0, 8)}; the user can undo it from the Wiki Inbox.`
-    record(root, context, 'edit', outcome.operation.pages.map((page) => [page.pageId, kind]))
-  }
-  return text
-}

package/src/memory/blocks.test.ts

@@ -1,78 +0,0 @@
-import { expect, test } from 'vitest'
-
-import { rootWithProject } from '../../tests/helpers'
-import { applyEdit, attached, DEFAULT_LIMIT, edit, PROJECT_LIMIT, render, saveAsUser, undoLast, type BlockInput, type Caller } from './blocks'
-import { readManifest, wikiDir } from './store'
-
-const agent = (id: string): Caller => ({ kind: 'agent', id, name: 'Nora' })
-const append = (text: string) => ({ kind: 'append' as const, text })
-
-test('edits apply with limits and exact replacement', () => {
-  expect(applyEdit('', append('Likes pnpm.'))).toBe('Likes pnpm.')
-  expect(applyEdit('A', append(' B '))).toBe('A\nB')
-  expect(applyEdit('Use npm.', { kind: 'replace', old: 'npm', new: 'pnpm' })).toBe('Use pnpm.')
-  expect(() => applyEdit('a a', { kind: 'replace', old: 'a', new: 'b' })).toThrow('2 times')
-  expect(() => applyEdit('a', { kind: 'replace', old: 'z', new: 'b' })).toThrow()
-  expect(() => applyEdit('a', append('  '))).toThrow()
-  expect(applyEdit('old', { kind: 'rethink', text: ' new ' })).toBe('new')
-})
-
-test('an agent gets its blocks, the user block and work project briefs', () => {
-  const root = rootWithProject()
-  const blocks = attached(root, agent('a1'), ['app', 'missing'])
-  expect(blocks.map((block) => block.front.label)).toEqual(['persona', 'notes', 'user', 'project/app'])
-  expect(blocks[0].id).toBe('blocks/agents/a1/persona')
-  expect(blocks[3].front.limit).toBe(PROJECT_LIMIT)
-  expect(attached(root, { kind: 'session', projectSlug: 'app' }, []).map((block) => block.front.label)).toEqual(['user', 'project/app'])
-})
-
-test('edits are revisioned, limited and undoable', () => {
-  const root = rootWithProject()
-  const wiki = wikiDir(root)
-  const nora = agent('a1')
-  expect(edit(root, nora, 'user', append('Prefers short answers.')).body).toBe('Prefers short answers.')
-  const revisions = readManifest(wiki, 'blocks/shared/user')
-  expect(revisions).toHaveLength(2)
-  expect(revisions[1].actor).toBe('Nora')
-  edit(root, nora, 'user', append('Works in Bangkok time.'))
-  expect(readManifest(wiki, 'blocks/shared/user')).toHaveLength(3)
-  expect(undoLast(wiki, 'blocks/shared/user').body).toBe('Prefers short answers.')
-  expect(undoLast(wiki, 'blocks/shared/user').body).toBe('')
-  expect(() => undoLast(wiki, 'blocks/shared/user')).toThrow()
-
-  expect(() => edit(root, nora, 'notes', { kind: 'rethink', text: 'x'.repeat(DEFAULT_LIMIT + 1) })).toThrow('memory_rethink')
-  expect(() => edit(root, nora, 'notes', append('key sk-ant-abc'))).toThrow('credential')
-  expect(() => edit(root, nora, 'nope', append('x'))).toThrow()
-})
-
-test('sessions edit only their project brief', () => {
-  const root = rootWithProject()
-  const session: Caller = { kind: 'session', projectSlug: 'app' }
-  expect(edit(root, session, 'project', append('Tauri 2 app.')).id).toBe('blocks/projects/app/brief')
-  expect(() => edit(root, session, 'user', append('x'))).toThrow('cannot edit')
-  expect(() => edit(root, session, 'persona', append('x'))).toThrow()
-  attached(root, agent('a1'), [])
-  expect(() => edit(root, session, 'blocks/agents/a1/persona', append('x'))).toThrow()
-  expect(() => edit(root, { kind: 'session', projectSlug: null }, 'project/app', append('x'))).toThrow()
-  // An agent may edit any project's brief, and its own blocks, but not another agent's.
-  expect(edit(root, agent('a1'), 'project/app', append('Uses pnpm.')).body).toContain('Uses pnpm.')
-  expect(() => edit(root, agent('a2'), 'blocks/agents/a1/persona', append('x'))).toThrow()
-})
-
-test('the user creates and restricts shared blocks', () => {
-  const root = rootWithProject()
-  const wiki = wikiDir(root)
-  const input = (id: string | null, label: string | null, agents: string[], readOnly: boolean): BlockInput => ({ id, label, body: 'We ship on Fridays.', description: 'Team habits.', limit: 500, readOnly, agents })
-  const created = saveAsUser(wiki, input(null, 'Team habits', ['a1'], false))
-  expect(created.id).toBe('blocks/shared/team-habits')
-  expect(() => saveAsUser(wiki, input(null, 'Team habits', [], false))).toThrow()
-  expect(() => saveAsUser(wiki, input(null, 'user', [], false))).toThrow()
-  expect(attached(root, agent('a1'), []).some((block) => block.id === created.id)).toBe(true)
-  expect(attached(root, agent('a2'), []).some((block) => block.id === created.id)).toBe(false)
-  expect(() => edit(root, agent('a2'), 'team-habits', append('x'))).toThrow()
-  saveAsUser(wiki, input(created.id, null, [], true))
-  expect(() => edit(root, agent('a1'), 'team-habits', append('x'))).toThrow('read-only')
-  const rendered = render(attached(root, agent('a1'), []), agent('a1'), false)
-  expect(rendered).toContain('<block label="team-habits" chars="19/500" read-only="true">')
-  expect(rendered).toContain('<block label="persona" chars="0/2000">')
-})