@xingular/harness 0.1.6 → 2.0.0

package/src/hub/schema.ts

@@ -0,0 +1,81 @@
+import { z } from 'zod'
+
+export const HUB_CATALOG_URL = 'https://raw.githubusercontent.com/tanntnny/xingular-hub/main/catalog.json'
+export const HUB_MAX_BYTES = 16 * 1024 * 1024
+
+const httpsUrl = z.string().max(2000).url().refine((value) => {
+  const url = new URL(value)
+  return url.protocol === 'https:' && !url.username && !url.password && !url.search && !url.hash && !url.port
+}, 'Use a public HTTPS URL without credentials, queries, or fragments.')
+const payload = {
+  url: httpsUrl,
+  sha256: z.string().regex(/^[a-f0-9]{64}$/),
+  bundled: z.string().max(HUB_MAX_BYTES).optional()
+}
+
+export const hubDeliverySchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('registry'), registryKind: z.enum(['skills', 'prompts', 'rules']), ...payload }).strict(),
+  z.object({ kind: z.literal('document'), ...payload }).strict(),
+  z.object({ kind: z.literal('pi-package'), source: z.string().max(2000).refine((source) =>
+    /^npm:(?:@[a-z0-9_.-]+\/)?[a-z0-9_.-]+@\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(source)
+    || /^git:https:\/\/github\.com\/[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+(?:\.git)?@[a-f0-9]{40}$/.test(source),
+  'Packages must use an exact npm version or a GitHub commit.') }).strict()
+])
+
+export const hubEntrySchema = z.object({
+  id: z.string().regex(/^[a-z0-9-]{1,64}\/[a-z0-9-]{1,64}$/),
+  title: z.string().min(1).max(100),
+  description: z.string().min(1).max(500),
+  publisher: z.string().min(1).max(100),
+  license: z.string().min(1).max(100),
+  version: z.string().regex(/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/),
+  category: z.string().regex(/^[a-z][a-z-]{0,40}$/),
+  channel: z.enum(['official', 'community']),
+  tags: z.array(z.string().max(60)).max(20),
+  requires: z.record(z.string(), z.string().regex(/^\d+\.\d+\.\d+$/)),
+  sourceUrl: httpsUrl,
+  delivery: hubDeliverySchema
+}).strict()
+
+export const hubCatalogSchema = z.object({
+  schemaVersion: z.literal(1),
+  entries: z.array(hubEntrySchema).max(2000)
+}).strict().superRefine((catalog, ctx) => {
+  const keys = new Set<string>()
+  catalog.entries.forEach((entry, index) => {
+    const key = `${entry.id}@${entry.version}`
+    if (keys.has(key)) ctx.addIssue({ code: 'custom', path: ['entries', index, 'id'], message: 'Duplicate catalog item version.' })
+    keys.add(key)
+  })
+})
+
+export const hubReceiptSchema = z.object({
+  entry: hubEntrySchema,
+  installedAt: z.string(),
+  resourceIds: z.array(z.string()),
+  document: z.string().nullable()
+}).strict()
+
+export const hubOverviewSchema = z.object({
+  entries: z.array(hubEntrySchema),
+  installed: z.array(hubReceiptSchema),
+  origin: z.enum(['bundled', 'cached', 'remote']),
+  refreshedAt: z.string().nullable(),
+  error: z.string().nullable(),
+  dataRoot: z.string().nullable(),
+  stateDir: z.string()
+})
+
+export type HubEntry = z.infer<typeof hubEntrySchema>
+export type HubCatalog = z.infer<typeof hubCatalogSchema>
+export type HubReceipt = z.infer<typeof hubReceiptSchema>
+export type HubOverview = z.infer<typeof hubOverviewSchema>
+
+export function meetsMinimum(actual: string, minimum: string): boolean {
+  const left = actual.split(/[.-]/).slice(0, 3).map(Number)
+  const right = minimum.split('.').map(Number)
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index]
+  }
+  return true
+}

package/src/index.ts

@@ -7,6 +7,7 @@
 // providers, a tool policy, a secret store, a directory of its own names, and a description of
 // its own parts as plugins. Everything else is reachable by path, e.g. `@xingular/harness/memory/wiki`.
 export { createHarness, Harness, type HarnessOptions, type Recovery } from './harness'
+export { hubCatalogSchema, hubEntrySchema, hubOverviewSchema, hubReceiptSchema, type HubCatalog, type HubEntry, type HubOverview, type HubReceipt } from './hub/schema'
 
 export { Bus, log, type Notice } from './core/bus'
 export { EMPTY_DIRECTORY, type Directory, type HarnessEnv } from './core/env'
@@ -15,7 +16,7 @@ export { findBinary, searchPath } from './core/path'
 
 export { fileSecretStore, memorySecretStore, secretKey, type SecretStore } from './accounts/secrets'
 export type { Account, AccountsOverview, Pool } from './accounts/store'
-export type { ModelOption } from './accounts/accounts'
+export type { AccountLoginSnapshot, ModelOption } from './accounts/accounts'
 export type { Capability, CapabilityCatalogue, CapabilityKind, CapabilityScope, CapabilitySet } from './capabilities/types'
 export type { RunCapabilitySnapshot } from './capabilities/runSnapshot'
 
@@ -46,11 +47,15 @@ export type { Effort } from './sessions/runner'
 
 export { describeTool, WIKI_TOOLS, WIKI_TOOL_NAMES, type WikiCall, type WikiToolDefinition } from './tools/definitions'
 export type { ToolProvider, ToolResult, ToolSession, ToolSpec } from './tools/types'
+export { SPAWN_SUBAGENT, SUBAGENT_RELATION } from './tools/spawnSubagent'
+export { maintenanceTools, MAINTENANCE_PLUGIN, MAINTENANCE_TOOL_NAMES } from './tools/maintenance'
+export type { CurationJob } from './memory/curation'
 export { webTools, WEB_PLUGIN, WEB_SEARCH_KEY, type WebToolOptions } from './web/tools'
+export { registryTools, REGISTRY_WRITE, PLUGIN_WRITE, REGISTRY_WRITE_PLUGIN, type RegistryToolOptions } from './tools/registryWrite'
 export { safeRequest, type WebRequest, type WebResponse } from './web/safeRequest'
 
 export type { BrokeredTools, BrokerSession, BrokerTool } from './mcp/service'
-export type { Connection, ConnectionInput } from './mcp/types'
+export type { Connection, ConnectionInput, AppOAuthClients } from './mcp/types'
 
 export { configureBuiltins, type RegistryItem, type RegistryState, type SkillBundleInput } from './skills/registry'
 
@@ -68,3 +73,8 @@ export { methods } from './server/methods'
 export { remoteDirectory, remotePolicy, remoteSecrets, remoteTools } from './server/remote'
 export { PROTOCOL_VERSION, RpcPeer, stdioTransport, type Handler, type Transport } from './server/rpc'
 export { attach, serve, type Served } from './server/serve'
+
+export { DEFAULT_SUBAGENT_DEPTH, MAX_SUBAGENT_DEPTH, type SubagentOptions, type SubagentInput } from './sessions/subagents'
+
+export { Subagents } from './sessions/subagentService'
+export { WAIT_SUBAGENTS, type SubagentResult, type SubagentSelection } from './sessions/subagents'

package/src/mcp/connections.ts

@@ -12,7 +12,7 @@ import { isDir } from '../memory/store'
 import type { RunEvent } from '../sessions/contracts'
 import * as attachments from '../plugins/attachments'
 import { connectionScopeMigrationComplete } from './scopeMigration'
-import { connectionCapabilityId, connectionInputSchema, connectionSchema, type Connection, type ConnectionInput, type LaunchConfig, type Scope } from './types'
+import { connectionCapabilityId, connectionInputSchema, connectionSchema, type AppOAuthClients, type Connection, type ConnectionInput, type LaunchConfig, type Scope } from './types'
 
 const OAUTH_STATE = 'oauth'
 const OAUTH_CLIENT_ID = 'oauth_client_id'
@@ -175,7 +175,8 @@ export class Connections {
     stateDir: string,
     private readonly secrets: SecretStore,
     private readonly bus: Bus,
-    private readonly attachmentRoot: () => string | null = () => null
+    private readonly attachmentRoot: () => string | null = () => null,
+    private readonly appClients: AppOAuthClients | null = null
   ) {
     this.path = join(stateDir, 'connections.json')
   }
@@ -468,23 +469,49 @@ export class Connections {
 
   // ---- OAuth state --------------------------------------------------------------------------
 
-  private requireOauth(id: string): void {
-    if (!this.list().some((item) => item.id === id && item.kind === 'remote' && item.auth === 'oauth')) throw notFound('Connection')
+  private requireOauth(id: string): Connection {
+    const connection = this.list().find((item) => item.id === id && item.kind === 'remote' && item.auth === 'oauth')
+    if (!connection) throw notFound('Connection')
+    return connection
   }
 
-  /** The saved sign-in of a connection, with the client the user registered, if any. */
+  /** The saved sign-in of a connection, with the client the user registered, or the application's own. */
   async oauthLoad(id: string): Promise<Record<string, unknown>> {
-    this.requireOauth(id)
+    const connection = this.requireOauth(id)
     const saved = (parsedContainer((await this.secret(id, OAUTH_STATE)) ?? '') ?? {}) as Record<string, unknown>
     const state = Array.isArray(saved) ? {} : saved
-    const clientId = await this.secret(id, OAUTH_CLIENT_ID)
-    if (clientId) {
-      const clientSecret = await this.secret(id, OAUTH_CLIENT_SECRET)
-      state.staticClient = { client_id: clientId, ...(clientSecret ? { client_secret: clientSecret } : {}) }
+    delete state.staticClient
+    if (connection.oauthClient === 'app') {
+      const client = await this.appClient(connection)
+      if (client) state.staticClient = { client_id: client.clientId, ...(client.clientSecret ? { client_secret: client.clientSecret } : {}) }
+    } else if (connection.oauthClient === 'user' || connection.oauthClient === null) {
+      const clientId = await this.secret(id, OAUTH_CLIENT_ID)
+      if (clientId) {
+        const clientSecret = await this.secret(id, OAUTH_CLIENT_SECRET)
+        state.staticClient = { client_id: clientId, ...(clientSecret ? { client_secret: clientSecret } : {}) }
+      }
     }
     return state
   }
 
+  /** The client this application registered for a catalog entry, if it has one. */
+  private async appClient(connection: Connection): Promise<{ clientId: string; clientSecret?: string } | null> {
+    if (!connection.catalogId) return null
+    return (await this.appClients?.get(connection.catalogId)) ?? null
+  }
+
+  /** Whether a sign-in can be started: a dynamic server registers itself, the others need a client. */
+  async hasSignInClient(connection: Connection): Promise<boolean> {
+    if (connection.oauthClient === 'user') return (await this.secret(connection.id, OAUTH_CLIENT_ID)) !== null
+    if (connection.oauthClient === 'app') return (await this.appClient(connection)) !== null
+    return true
+  }
+
+  /** The catalog entries this application can sign in for without asking for a client. */
+  availableAppClients(): string[] {
+    return this.appClients?.ids() ?? []
+  }
+
   async oauthSave(id: string, state: Record<string, unknown>): Promise<void> {
     this.requireOauth(id)
     const { staticClient: _static, ...saved } = state ?? {}
@@ -515,7 +542,7 @@ export class Connections {
     if (remote) {
       if (!webUrl(connection.url)) throw invalid('Server URL must be an https:// address.')
       if (!['none', 'headers', 'oauth'].includes(connection.auth)) throw invalid('Unsupported sign-in method.')
-      if (connection.oauthClient && !['dynamic', 'user'].includes(connection.oauthClient)) throw invalid('Unsupported OAuth client.')
+      if (connection.oauthClient && !['dynamic', 'user', 'app'].includes(connection.oauthClient)) throw invalid('Unsupported OAuth client.')
       Object.assign(connection, { command: '', args: [], cwd: null })
       if (connection.auth !== 'oauth') Object.assign(connection, { oauthClient: null, oauthScopes: [] })
     } else {
@@ -533,7 +560,7 @@ export class Connections {
     connection.envKeys = [...(existing?.envKeys ?? [])]
     connection.headerKeys = [...(existing?.headerKeys ?? [])]
     // A sign-in belongs to one server and one client; never carry it to another.
-    const sameServer = (existing?.url ?? null) === connection.url && (existing?.auth ?? '') === connection.auth && !oauthCredentials
+    const sameServer = (existing?.url ?? null) === connection.url && (existing?.auth ?? '') === connection.auth && existing?.oauthClient === connection.oauthClient && existing?.catalogId === connection.catalogId && !oauthCredentials
     if (!sameServer || connection.auth !== 'oauth') await this.forgetSignIn(connection.id)
     connection.authState = connection.auth === 'oauth' ? (sameServer ? (existing?.authState ?? 'signed_out') : 'signed_out') : null
     if (oauthCredentials) {

package/src/mcp/service.test.ts

@@ -8,7 +8,7 @@ import { McpServer, WebStandardStreamableHTTPServerTransport } from '@modelconte
 import { afterEach, describe, expect, it } from 'vitest'
 
 import { memorySecretStore } from '../accounts/secrets'
-import { createHarness, type Harness } from '../harness'
+import { createHarness, type Harness, type HarnessOptions } from '../harness'
 import type { RunEvent } from '../sessions/contracts'
 import type { ToolPolicy } from '../sessions/policy'
 import type { PiSessionLike } from '../sessions/runner'
@@ -106,12 +106,12 @@ afterEach(async () => {
 const tick = (ms = 30) => new Promise((resolve) => setTimeout(resolve, ms))
 
 /** A harness with one live run whose session keeps going until the test releases it. */
-async function live(policy: ToolPolicy = {}) {
+async function live(policy: ToolPolicy = {}, extra: Partial<HarnessOptions> = {}) {
   let release: () => void = () => undefined
   const stateDir = mkdtempSync(join(tmpdir(), 'harness-mcp-state-'))
   const secrets = memorySecretStore()
   const session: PiSessionLike = { sessionId: 'native', subscribe: () => () => undefined, prompt: () => new Promise<void>((resolve) => (release = resolve)), sendCustomMessage: async () => undefined, abort: async () => release(), dispose: () => undefined }
-  const harness = createHarness({ dataRoot: mkdtempSync(join(tmpdir(), 'harness-mcp-data-')), stateDir, secrets, policy, sessionFactory: async () => session })
+  const harness = createHarness({ dataRoot: mkdtempSync(join(tmpdir(), 'harness-mcp-data-')), stateDir, secrets, policy, sessionFactory: async () => session, ...extra })
   open.push(harness)
   harness.accounts.create('Main', 'apiKey')
   const events: RunEvent[] = []
@@ -277,6 +277,7 @@ describe('remote connected apps', () => {
     await expect(harness.apps.save({ name: '', kind: 'local', command: 'x' })).rejects.toThrow('A name, executable')
     await expect(harness.apps.save({ ...local, env: { 'BAD NAME': 'x' } })).rejects.toThrow('environment variable')
     await expect(harness.apps.save({ ...remote, url: 'https://x.example/mcp', auth: 'headers', headers: { 'X-Key': 'a\nb' } })).rejects.toThrow('header')
+    await expect(harness.apps.save({ ...remote, url: 'https://x.example/mcp', auth: 'oauth', oauthClient: 'whoever' })).rejects.toThrow('Unsupported OAuth client')
     const workspace = await harness.apps.save({ name: 'Xingular Workspace', kind: 'workspace', command: process.execPath, enabled: true, global: true })
     expect(() => harness.apps.connections.allowTool(workspace.id, 'x_workspace_mutation_apply')).toThrow('one at a time')
     await harness.apps.remove(workspace.id)
@@ -373,4 +374,49 @@ describe('signing in to a remote connected app', () => {
     expect(server.seen.tokenRequests[0]).toContain('fixture-code')
     expect(server.seen.tokenRequests[0]).toMatch(/own-client|b3duLWNsaWVudDpvd24tc2VjcmV0/)
   })
+
+  it('signs in with the application\'s own client, keeps it out of storage, and offers it only for that catalog entry', async () => {
+    const server = await oauthFixture()
+    const { harness, secrets } = await live({}, { oauthClients: { ids: () => ['fixture-app'], get: async (id) => (id === 'fixture-app' ? { clientId: 'app-client', clientSecret: 'app-secret' } : null) } })
+    harness.bus.on((notice) => {
+      if (notice.type === 'connections.openUrl') void fetch(String(notice.url))
+    })
+    expect(harness.apps.appClients()).toEqual({ catalogIds: ['fixture-app'] })
+    const saved = await harness.apps.save({ name: 'App client', kind: 'remote', enabled: true, global: true, url: server.url, auth: 'oauth', oauthClient: 'app', catalogId: 'fixture-app', oauthScopes: ['read'] })
+    expect((await harness.apps.signIn(saved.id)).authState).toBe('signed_in')
+    // No client of its own is registered, and the application's client is what the provider sees.
+    expect(server.seen.registered).toBe(0)
+    expect(server.seen.authorizeUrls[0].searchParams.get('client_id')).toBe('app-client')
+    // Neither the saved connection nor the secret store ever holds the application's client secret.
+    expect(JSON.stringify(harness.apps.connections.list())).not.toContain('app-secret')
+    expect(JSON.stringify([...secrets.values.entries()])).not.toContain('app-secret')
+    expect(JSON.parse(secrets.values.get(`mcp--${saved.id}/oauth`)!).tokens).toMatchObject({ refresh_token: 'fixture-refresh' })
+  })
+
+  it('uses the application client and resets sign-in when switching from a saved user client', async () => {
+    const server = await oauthFixture()
+    const { harness, secrets } = await live({}, { oauthClients: { ids: () => ['fixture-app'], get: async (id) => (id === 'fixture-app' ? { clientId: 'app-client', clientSecret: 'app-secret' } : null) } })
+    harness.bus.on((notice) => {
+      if (notice.type === 'connections.openUrl') void fetch(String(notice.url))
+    })
+    const user = await harness.apps.save({ name: 'Switched client', kind: 'remote', enabled: true, global: true, url: server.url, auth: 'oauth', oauthClient: 'user', oauthCredentials: { clientId: 'user-client', clientSecret: 'user-secret' } })
+    const signedInUser = await harness.apps.signIn(user.id)
+    expect(signedInUser.authState).toBe('signed_in')
+
+    const app = await harness.apps.save({ ...user, oauthClient: 'app', catalogId: 'fixture-app' })
+    expect(app.authState).toBe('signed_out')
+    expect(secrets.values.has(`mcp--${user.id}/oauth`)).toBe(false)
+    await harness.apps.signIn(user.id)
+
+    expect(server.seen.authorizeUrls.map((url) => url.searchParams.get('client_id'))).toEqual(['user-client', 'app-client'])
+    expect(server.seen.tokenRequests[1]).toMatch(/app-client|YXBwLWNsaWVudDphcHAtc2VjcmV0/)
+  })
+
+  it('refuses an application sign-in this build has no client for, naming the reason', async () => {
+    const { harness } = await live()
+    const saved = await harness.apps.save({ name: 'No client', kind: 'remote', enabled: true, global: true, url: 'https://example.com/mcp', auth: 'oauth', oauthClient: 'app', catalogId: 'google-drive', oauthScopes: [] })
+    expect(harness.apps.appClients()).toEqual({ catalogIds: [] })
+    await expect(harness.apps.signIn(saved.id)).rejects.toThrow(/no app sign-in/)
+    expect(harness.apps.connections.find(saved.id).authState).toBe('signed_out')
+  })
 })

package/src/mcp/service.ts

@@ -20,7 +20,7 @@ import type { ToolSession, ToolSpec } from '../tools/types'
 import { allowed, Connections, webUrl } from './connections'
 import { isSignInRequired, McpManager, signInRequired } from './manager'
 import { signIn, type OAuthHost } from './oauth'
-import type { Connection, HttpConfig, LaunchConfig, McpSource, McpTrace } from './types'
+import type { AppOAuthClients, Connection, HttpConfig, LaunchConfig, McpSource, McpTrace } from './types'
 
 /** A session's access to the broker. A terminal session presents `token`; an SDK session holds the object. */
 export interface BrokerSession {
@@ -118,6 +118,8 @@ export interface ConnectedAppsOptions {
   bus: Bus
   runs: RunRegistry
   policy: ToolPolicy
+  /** The application's own registered OAuth clients, if it has any. */
+  oauthClients?: AppOAuthClients
 }
 
 /** The scope a plugin hook's connections are opened under: they belong to no session. */
@@ -134,7 +136,7 @@ export class ConnectedApps implements SessionBroker {
   private brokered: BrokeredTools | null = null
 
   constructor(private readonly options: ConnectedAppsOptions) {
-    this.connections = new Connections(options.stateDir, options.secrets, options.bus, () => options.env.root)
+    this.connections = new Connections(options.stateDir, options.secrets, options.bus, () => options.env.root, options.oauthClients ?? null)
     this.oauth = {
       clientName: options.env.productName,
       load: (id) => this.connections.oauthLoad(id),
@@ -469,7 +471,11 @@ export class ConnectedApps implements SessionBroker {
   async signIn(connectionId: string): Promise<Connection> {
     const connection = this.connections.find(connectionId)
     if (connection.kind !== 'remote' || connection.auth !== 'oauth') throw invalid('This connection does not use browser sign-in.')
-    if (connection.oauthClient === 'user' && !(await this.connections.hasOauthClient(connection.id))) throw invalid('Add your OAuth client ID before signing in.')
+    if (!(await this.connections.hasSignInClient(connection))) {
+      throw invalid(connection.oauthClient === 'app'
+        ? 'This connector has no app sign-in in this build. Enable its OAuth client or use your own client.'
+        : 'Add your OAuth client ID before signing in.')
+    }
     await signIn(this.oauth, (await this.connections.launch(connection)) as HttpConfig)
     const updated = this.connections.update(connectionId, (item) => Object.assign(item, { authState: 'signed_in', error: null }))
     await this.manager.close(connectionId)
@@ -477,6 +483,11 @@ export class ConnectedApps implements SessionBroker {
     return updated
   }
 
+  /** The catalog entries this application can sign in for, so a client need not be added by hand. */
+  appClients(): { catalogIds: string[] } {
+    return { catalogIds: this.connections.availableAppClients() }
+  }
+
   async signOut(connectionId: string): Promise<Connection> {
     const updated = await this.connections.signOut(connectionId)
     this.cancelConnection(connectionId)

package/src/mcp/types.ts

@@ -7,6 +7,16 @@ import { z } from 'zod'
 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}`
 

package/src/memory/api.ts

@@ -11,6 +11,7 @@ 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'
@@ -104,7 +105,7 @@ export function search(env: HarnessEnv, context: CallerContext, params: Params):
   // 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) => !(hit.kind === 'block' && hit.type === 'agent') || (own !== null && hit.id.startsWith(own)))
+    .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)
@@ -126,7 +127,7 @@ export function read(env: HarnessEnv, context: CallerContext, params: Params): s
   // 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 (own === null || `blocks/agents/${entry.block.owner}/` !== own) throw notFound('Wiki entry')
+    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'
@@ -272,13 +273,26 @@ export function propose(env: HarnessEnv, context: CallerContext, params: Params)
     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) {

package/src/memory/blocks.ts

@@ -52,7 +52,7 @@ export interface Block {
 export type Caller =
   | { kind: 'user' }
   /** An agent with blocks of its own, and the name recorded on its revisions. */
-  | { kind: 'agent'; id: string; name: string }
+  | { kind: 'agent'; id: string; name: string; vaultAccess?: 'self' | 'propose' | 'curator' }
   /** A session without blocks of its own, and its project, if any. */
   | { kind: 'session'; projectSlug: string | null }
 
@@ -192,6 +192,8 @@ export function editRefusal(caller: Caller, block: Block): string | null {
   const label = block.front.label
   if (caller.kind === 'user') return null
   if (block.front.readOnly) return `The ${label} block is read-only; only the user can change it.`
+  if (caller.kind === 'agent' && caller.vaultAccess === 'propose') return 'Memory changes are proposals in this session. Submit the block change with wiki_propose; the next memory merge applies it.'
+  if (caller.kind === 'agent' && caller.vaultAccess === 'self' && (block.scope !== 'agent' || block.owner !== caller.id || !['persona', 'notes'].includes(label))) return 'This field is outside your writable memory. Submit a block change with wiki_propose for the curator to review.'
   if (caller.kind === 'agent') {
     if (block.scope === 'agent') return block.owner === caller.id ? null : 'That block belongs to another agent.'
     if (block.scope === 'shared') return !block.front.agents.length || block.front.agents.includes(caller.id) ? null : `The ${label} block is not attached to you.`

package/src/memory/caller.ts

@@ -10,11 +10,23 @@ import * as blocks from './blocks'
  * never limits what can be read.
  */
 export interface CallerContext {
+  /** Opaque, host-owned policy data frozen when this session starts. The harness only forwards it to the embedding app's tool policy. */
+  policyContext?: unknown
+  /**
+   * Trusted, frozen vault mutation capability supplied by an embedding host. `self` writes its own
+   * persona and notes directly and proposes the rest; `propose` writes nothing directly; `curator`
+   * applies proposals.
+   */
+  vaultAccess?: 'self' | 'propose' | 'curator'
+  maintenanceJobId?: string | null
+  maintenanceJobIds?: string[]
   runId?: string | null
   sessionId?: string | null
   projectId?: string | null
   /** The agent calling; it decides which memory blocks are attached and editable. */
   agentId?: string | null
+  /** Agents whose conversations this caller may not recall (opaque ids from the embedding host). */
+  recallExcludeAgents?: string[] | null
   /** The agent's name, recorded on the revisions it makes. */
   agentName?: string | null
   /** Projects whose briefs the agent carries, most recently active first. */
@@ -42,7 +54,7 @@ export function projectOf(root: string, context: CallerContext): Project | null
 export function blockCaller(env: HarnessEnv, context: CallerContext): blocks.Caller {
   if (isSession(context)) return { kind: 'session', projectSlug: projectOf(env.root, context)?.slug ?? null }
   if (!context.agentId) throw invalid('Memory blocks need an agent or a Harness session.')
-  return { kind: 'agent', id: context.agentId, name: context.agentName ?? env.directory.agentName(context.agentId) ?? context.agentId }
+  return { kind: 'agent', id: context.agentId, name: context.agentName ?? env.directory.agentName(context.agentId) ?? context.agentId, vaultAccess: context.vaultAccess === 'propose' ? 'propose' : context.vaultAccess ? 'self' : undefined }
 }
 
 /** The blocks in the caller's context: an agent also carries the briefs of its active projects. */