@north-light/crouter 0.3.352 → 0.3.354

package/dist/pi-extensions/canvas-bash-valve.js

@@ -1,4 +1,5 @@
-var te=Object.defineProperty;var o=(r,n)=>te(r,"name",{value:n,configurable:!0});import{envBashAutoBgDeadlineMs as oe,envBashValveMs as ie,envNodeId as se}from"../shared/env.js";import{spawn as de}from"node:child_process";import{closeSync as ae,existsSync as B,mkdirSync as G,openSync as ce,readFileSync as ue,readSync as fe,rmSync as V,statSync as K,writeFileSync as y}from"node:fs";import{homedir as le}from"node:os";import{dirname as be}from"node:path";import{performance as O}from"node:perf_hooks";import{backgroundBashJob as z,bashJobPaths as pe,cancelBashJobProcessTree as he,formatBashElapsed as q,newBashJobId as me,normalizeBashJobPurpose as ge,readBashNiceness as we,writeJobDeadlineMs as ye}from"../core/bash-jobs.js";import{BASH_JOB_SUPERVISOR_SCRIPT as Se}from"../core/bash-job-supervisor.js";import{MAX_BACKGROUND_BASH_LOG_BYTES as ir,BACKGROUND_BASH_LOG_TRUNCATION_MARKER as sr}from"../core/bash-job-supervisor.js";import{startBrokerBashJob as Ee,stopBrokerBashJob as ve}from"../core/runtime/broker/daemon-ops.js";import{bashCommandRefusal as Be}from"../core/bash-guard.js";import{capturePidIdentities as Ie}from"../core/canvas/pid.js";import{readConfig as je}from"../core/config.js";import{PREVIEW_RESULT_PATH_ENV as _e,previewResultPath as Re}from"../core/preview-result-path.js";import{resolveAdmittedHostCommand as ke}from"../core/runtime/spawn-env.js";import{Type as P}from"typebox";import{createBashToolDefinition as W}from"@earendil-works/pi-coding-agent";const Le=200;function xe(){return ie()}o(xe,"resolveValveMs");function Te(r){return pe(r,me())}o(Te,"makeJobPaths");const I=new Set;let X=!1;function Y(){for(const r of[...I])try{z(r),I.delete(r)}catch(n){process.stderr.write(`crtr: failed to background bash job ${r.jobId} during broker termination: ${n.message}
-`)}}o(Y,"backgroundLiveJobsForTermination");function Ae(){X||(X=!0,process.prependListener("SIGTERM",Y),process.platform!=="win32"&&process.prependListener("SIGHUP",Y))}o(Ae,"installTerminationHandoff");const Oe=64*1024;function C(r,n,i){let s;try{s=K(r)}catch{return n}if(s.size<=n)return n;const c=ce(r,"r");try{for(;n<s.size;){const m=Math.min(Oe,s.size-n),f=Buffer.allocUnsafe(m),d=fe(c,f,0,m,n);if(d===0)break;i(f.subarray(0,d)),n+=d}return n}finally{ae(c)}}o(C,"tailOnce");function h(r){try{V(r,{recursive:!0,force:!0})}catch{}}o(h,"cleanupJobDir");function Pe(r){try{const n=ue(r,"utf8").trim(),i=Number(n);return Number.isFinite(i)?i:null}catch{return null}}o(Pe,"readExitCode");function Ce(r){try{if(K(r).isDirectory())return{cwd:r}}catch{}const n=le();return{cwd:n,warning:`[working directory no longer exists: ${r}; running from ${n}]
-`}}o(Ce,"resolveExecutionCwd");function Q(r,n,i=()=>null,s){return{exec:o((c,m,{onData:f,signal:d,timeout:p,env:k})=>new Promise((j,a)=>{const _=i();if(d?.aborted){a(new Error("aborted"));return}const L=Be(c,m);if(L!==null){a(new Error(L));return}const e=Te(n);G(e.dir,{recursive:!0}),y(e.cmdSh,c),y(e.jobLog,""),y(e.jobRun,""),_!==null&&y(e.jobPurpose,_);let g=0,x=!1,u,w,S,$=!1;const J=process.platform==="linux",M=O.now(),Z=xe();let T;const ee=o(()=>{T&&clearInterval(T),d&&d.removeEventListener("abort",D),I.delete(e)},"teardown"),l=o(t=>{x||(x=!0,ee(),t())},"finish");function A(t=!1){const b=q(O.now()-M);let U="";if(t){const F=oe();ye(e,Date.now()+F),U=`It will be CANCELED in ${q(F)} unless you claim it: crtr node bash extend ${e.jobId} --for <duration> (or --keep to run to completion). `}const ne=`
-[backgrounded as job ${e.jobId} after ${b} in the foreground${t?" (auto)":""}. `+U+`It will interrupt you with a message when it exits. Watch: tail -f ${e.jobLog} ; stop: crtr node bash kill ${e.jobId}]`;f(Buffer.from(ne)),l(()=>j({exitCode:0}))}o(A,"finishBackground");function N(){g=C(e.jobLog,g,f);const t=Pe(e.jobExit);l(()=>j({exitCode:t})),h(e.dir)}o(N,"finishForeground");function re(t=!1){const b=z(e);if(b==="backgrounded"||b==="already-backgrounded"){A(t);return}if(b==="finished"){N();return}l(()=>a(new Error(`bash job ${e.jobId} disappeared before it could be backgrounded`))),h(e.dir)}o(re,"requestBackground");function R(t){if(!(x||$)){if(g=C(e.jobLog,g,f),B(e.jobBg)){A();return}if(!B(e.jobExit)){if(u===void 0){S??=t;return}if(J){$=!0,ve(r,e.jobId).then(()=>{l(()=>a(t)),h(e.dir)},b=>l(()=>a(b)));return}u!==void 0&&w!==void 0&&he(u,w),l(()=>a(t)),h(e.dir)}}}o(R,"requestStop");function D(){R(new Error("aborted"))}o(D,"onAbort"),d&&d.addEventListener("abort",D,{once:!0});const E=Ce(m);E.warning&&f(Buffer.from(E.warning));let v=k??process.env;s!==void 0&&(G(be(s),{recursive:!0}),V(s,{force:!0}),v={...v,[_e]:s});const H=ke("bash",v,E.cwd);if(J)Ee(r,{job_id:e.jobId,cwd:E.cwd,env:v}).then(({pid:t})=>{u=t,w=`launcher:${t}`,I.add(e),S!==void 0&&R(S)},t=>{l(()=>a(t)),h(e.dir)});else{const t=de(H,["-c",Se,"--",e.cmdSh,e.jobLog,e.jobExit,e.jobRun,e.jobDone,e.jobBg,e.jobId,r,H,String(we(n)),process.execPath,"direct"],{cwd:E.cwd,detached:!0,stdio:"ignore",env:v});if(t.on("error",b=>{l(()=>a(b)),h(e.dir)}),u=t.pid,u!==void 0){if(w=Ie([u])?.get(u),w===void 0){try{process.kill(-u,"SIGKILL")}catch{}l(()=>a(new Error(`bash job ${e.jobId} started without a process identity`))),h(e.dir);return}y(e.jobPgid,String(u)),y(e.jobPgidIdentity,w),I.add(e),S!==void 0&&R(S)}t.unref()}T=setInterval(()=>{if(g=C(e.jobLog,g,f),B(e.jobDone)){N();return}if(B(e.jobBg)){A();return}if(B(e.jobExit))return;const t=O.now()-M;if(p!==void 0&&p>0){t>=p*1e3&&R(new Error(`timeout:${p}`));return}t>=Z&&re(!0)},Le)}),"exec")}}o(Q,"createValveOperations");const $e=["One short clause naming what this step is FOR, in the words of the person you",'are working for \u2014 "Reading the Acme thread", not "Fetching emails" and never','"Running GMAIL_FETCH_EMAILS". A person reads this while the command runs; it',"is the only thing they see of this step. Under about eight words. Omit it for","steps that only touch your own scratch work."].join(" ");function Je(r){return{...r,parameters:P.Object({purpose:P.Optional(P.String({description:$e})),...r.parameters.properties})}}o(Je,"withPurpose");function Me(r,n,i,s){const c=W(i,{operations:Q(r,n)});return{...s?Je(c):c,execute:o((d,p,k,j,a)=>{const _=s?ge(p.purpose):null;return W(i,{operations:Q(r,n,()=>_,Re(d))}).execute(d,p,k,j,a)},"execute")}}o(Me,"createValveToolDefinition");function Ne(r){const n=se();if(n===void 0||n.trim()==="")return;const i=process.env.CRTR_CONTEXT_DIR;i===void 0||i.trim()===""||(Ae(),r.on("session_start",(s,c)=>{r.registerTool(Me(n,i,c.cwd,je("user").bash_tool_purpose))}))}o(Ne,"default");export{sr as BACKGROUND_BASH_LOG_TRUNCATION_MARKER,ir as MAX_BACKGROUND_BASH_LOG_BYTES,Q as createValveOperations,Me as createValveToolDefinition,Ne as default};
+var de=Object.defineProperty;var o=(r,n)=>de(r,"name",{value:n,configurable:!0});import{envBashAutoBgDeadlineMs as ae,envBashValveMs as ce,envNodeId as ue}from"../shared/env.js";import{spawn as fe}from"node:child_process";import{closeSync as le,existsSync as j,mkdirSync as K,openSync as be,readFileSync as z,readSync as pe,rmSync as W,statSync as q,writeFileSync as y}from"node:fs";import{homedir as he}from"node:os";import{dirname as me}from"node:path";import{performance as A}from"node:perf_hooks";import{backgroundBashJob as X,bashJobPaths as ge,cancelBashJobProcessTree as we,formatBashElapsed as Y,newBashJobId as ye,normalizeBashJobPurpose as Se,readBashNiceness as ve,writeJobDeadlineMs as Ee}from"../core/bash-jobs.js";import{BASH_JOB_SUPERVISOR_SCRIPT as Ie}from"../core/bash-job-supervisor.js";import{MAX_BACKGROUND_BASH_LOG_BYTES as cr,BACKGROUND_BASH_LOG_TRUNCATION_MARKER as ur}from"../core/bash-job-supervisor.js";import{recordBackgroundedJob as je,startBrokerBashJob as Be,stopBrokerBashJob as _e}from"../core/runtime/broker/daemon-ops.js";import{bashCommandRefusal as ke}from"../core/bash-guard.js";import{capturePidIdentities as Re}from"../core/canvas/pid.js";import{readConfig as Le}from"../core/config.js";import{PREVIEW_RESULT_PATH_ENV as xe,previewResultPath as Te}from"../core/preview-result-path.js";import{resolveAdmittedHostCommand as Oe}from"../core/runtime/spawn-env.js";import{Type as P}from"typebox";import{createBashToolDefinition as Q}from"@earendil-works/pi-coding-agent";const Ae=200;function Pe(){return ce()}o(Pe,"resolveValveMs");function Ce(r){return ge(r,ye())}o(Ce,"makeJobPaths");const B=new Set;let Z=!1;function ee(){for(const r of[...B])try{X(r),B.delete(r)}catch(n){process.stderr.write(`crtr: failed to background bash job ${r.jobId} during broker termination: ${n.message}
+`)}}o(ee,"backgroundLiveJobsForTermination");function $e(){Z||(Z=!0,process.prependListener("SIGTERM",ee),process.platform!=="win32"&&process.prependListener("SIGHUP",ee))}o($e,"installTerminationHandoff");const Je=64*1024;function C(r,n,i){let s;try{s=q(r)}catch{return n}if(s.size<=n)return n;const u=be(r,"r");try{for(;n<s.size;){const m=Math.min(Je,s.size-n),l=Buffer.allocUnsafe(m),d=pe(u,l,0,m,n);if(d===0)break;i(l.subarray(0,d)),n+=d}return n}finally{le(u)}}o(C,"tailOnce");function h(r){try{W(r,{recursive:!0,force:!0})}catch{}}o(h,"cleanupJobDir");function Ne(r){try{const n=z(r,"utf8").trim(),i=Number(n);return Number.isFinite(i)?i:null}catch{return null}}o(Ne,"readExitCode");function Me(r){try{if(q(r).isDirectory())return{cwd:r}}catch{}const n=he();return{cwd:n,warning:`[working directory no longer exists: ${r}; running from ${n}]
+`}}o(Me,"resolveExecutionCwd");function re(r,n,i=()=>null,s){return{exec:o((u,m,{onData:l,signal:d,timeout:p,env:x})=>new Promise((_,c)=>{const k=i();if(d?.aborted){c(new Error("aborted"));return}const T=ke(u,m);if(T!==null){c(new Error(T));return}const e=Ce(n);K(e.dir,{recursive:!0}),y(e.cmdSh,u),y(e.jobLog,""),y(e.jobRun,""),k!==null&&y(e.jobPurpose,k);let g=0,R=!1,f,w,S,$=!1;const J=process.platform==="linux",N=A.now(),ne=Pe();let v;const te=o(()=>{v&&clearInterval(v),d&&d.removeEventListener("abort",U),B.delete(e)},"teardown"),b=o(t=>{R||(R=!0,te(),t())},"finish");let M=!1;function O(t=!1){R||M||(M=!0,v&&clearInterval(v),je(r,e.jobId,{command:z(e.cmdSh,"utf8"),job_dir:e.dir,log_path:e.jobLog}).then(()=>D(t,""),a=>D(t,`
+[crtr could not record job ${e.jobId} (${a.message}); it will NOT message you when it exits. Watch its log.]`)))}o(O,"finishBackground");function D(t,a){const ie=Y(A.now()-N);let G="";if(t){const V=ae();Ee(e,Date.now()+V),G=`It will be CANCELED in ${Y(V)} unless you claim it: crtr node bash extend ${e.jobId} --for <duration> (or --keep to run to completion). `}const se=`
+[backgrounded as job ${e.jobId} after ${ie} in the foreground${t?" (auto)":""}. `+G+(a===""?"It will interrupt you with a message when it exits. ":"")+`Watch: tail -f ${e.jobLog} ; stop: crtr node bash kill ${e.jobId}]`;l(Buffer.from(se+a)),b(()=>_({exitCode:0}))}o(D,"handOff");function H(){g=C(e.jobLog,g,l);const t=Ne(e.jobExit);b(()=>_({exitCode:t})),h(e.dir)}o(H,"finishForeground");function oe(t=!1){const a=X(e);if(a==="backgrounded"||a==="already-backgrounded"){O(t);return}if(a==="finished"){H();return}b(()=>c(new Error(`bash job ${e.jobId} disappeared before it could be backgrounded`))),h(e.dir)}o(oe,"requestBackground");function L(t){if(!(R||$)){if(g=C(e.jobLog,g,l),j(e.jobBg)){O();return}if(!j(e.jobExit)){if(f===void 0){S??=t;return}if(J){$=!0,_e(r,e.jobId).then(()=>{b(()=>c(t)),h(e.dir)},a=>b(()=>c(a)));return}f!==void 0&&w!==void 0&&we(f,w),b(()=>c(t)),h(e.dir)}}}o(L,"requestStop");function U(){L(new Error("aborted"))}o(U,"onAbort"),d&&d.addEventListener("abort",U,{once:!0});const E=Me(m);E.warning&&l(Buffer.from(E.warning));let I=x??process.env;s!==void 0&&(K(me(s),{recursive:!0}),W(s,{force:!0}),I={...I,[xe]:s});const F=Oe("bash",I,E.cwd);if(J)Be(r,{job_id:e.jobId,cwd:E.cwd,env:I}).then(({pid:t})=>{f=t,w=`launcher:${t}`,B.add(e),S!==void 0&&L(S)},t=>{b(()=>c(t)),h(e.dir)});else{const t=fe(F,["-c",Ie,"--",e.cmdSh,e.jobLog,e.jobExit,e.jobRun,e.jobDone,F,String(ve(n)),process.execPath],{cwd:E.cwd,detached:!0,stdio:"ignore",env:I});if(t.on("error",a=>{b(()=>c(a)),h(e.dir)}),f=t.pid,f!==void 0){if(w=Re([f])?.get(f),w===void 0){try{process.kill(-f,"SIGKILL")}catch{}b(()=>c(new Error(`bash job ${e.jobId} started without a process identity`))),h(e.dir);return}y(e.jobPgid,String(f)),y(e.jobPgidIdentity,w),B.add(e),S!==void 0&&L(S)}t.unref()}v=setInterval(()=>{if(g=C(e.jobLog,g,l),j(e.jobDone)){H();return}if(j(e.jobBg)){O();return}if(j(e.jobExit))return;const t=A.now()-N;if(p!==void 0&&p>0){t>=p*1e3&&L(new Error(`timeout:${p}`));return}t>=ne&&oe(!0)},Ae)}),"exec")}}o(re,"createValveOperations");const De=["One short clause naming what this step is FOR, in the words of the person you",'are working for \u2014 "Reading the Acme thread", not "Fetching emails" and never','"Running GMAIL_FETCH_EMAILS". A person reads this while the command runs; it',"is the only thing they see of this step. Under about eight words. Omit it for","steps that only touch your own scratch work."].join(" ");function He(r){return{...r,parameters:P.Object({purpose:P.Optional(P.String({description:De})),...r.parameters.properties})}}o(He,"withPurpose");function Ue(r,n,i,s){const u=Q(i,{operations:re(r,n)});return{...s?He(u):u,execute:o((d,p,x,_,c)=>{const k=s?Se(p.purpose):null;return Q(i,{operations:re(r,n,()=>k,Te(d))}).execute(d,p,x,_,c)},"execute")}}o(Ue,"createValveToolDefinition");function Fe(r){const n=ue();if(n===void 0||n.trim()==="")return;const i=process.env.CRTR_CONTEXT_DIR;i===void 0||i.trim()===""||($e(),r.on("session_start",(s,u)=>{r.registerTool(Ue(n,i,u.cwd,Le("user").bash_tool_purpose))}))}o(Fe,"default");export{ur as BACKGROUND_BASH_LOG_TRUNCATION_MARKER,cr as MAX_BACKGROUND_BASH_LOG_BYTES,re as createValveOperations,Ue as createValveToolDefinition,Fe as default};

package/dist/pi-extensions/canvas-context-intro.js

@@ -1,2 +1,2 @@
-var C=Object.defineProperty;var s=(t,n)=>C(t,"name",{value:n,configurable:!0});import{envNodeId as y}from"../shared/env.js";import{CONTEXT_INTRO_CUSTOM_TYPE as c,formatCard as b}from"../shared/generated-context.js";import{brokerContext as p,brokerExtensionState as f,commitBrokerContext as T}from"../core/runtime/broker/daemon-ops.js";import{buildForkBearingsFromState as l}from"../core/runtime/broker-extension-render.js";import{acknowledgePersonaBaseline as h}from"../core/runtime/broker-persona-guidance.js";import{situationalContextEnvelope as x}from"../core/runtime/situational-context.js";import{clearSessionCache as I}from"../core/substrate/session-cache.js";async function A(t){return(await p(t,"baseline")).content}s(A,"buildContextIntro");async function j(t){const n=await f(t);return l(n,x(t)??"")}s(j,"buildForkContextIntro");function g(t){const n=t.content;return typeof n=="string"?n:Array.isArray(n)?n.filter(r=>typeof r?.text=="string").map(r=>r.text).join(`
-`):""}s(g,"entryText");function _(t){t.on("session_start",async(n,r)=>{const e=y();if(e===void 0||e.trim()==="")return;const m=n?.reason,a=await f(e);if(a.warm_spare||m==="new"&&a.node.parent===null)return;m==="new"&&I();const d=r.sessionManager.getBranch().filter(o=>o.type==="custom_message"&&o.customType===c);if(d.some(o=>o.details?.nodeId===e||g(o).includes(e)))return;const i=await p(e,d.length>0?"compact":"baseline"),w=i.compact?l(a,x(e)??""):i.content,u=b("bearings",{},w);if(t.sendMessage({customType:c,content:u,display:!0,details:{nodeId:e}}),!r.sessionManager.getBranch().some(o=>o.type==="custom_message"&&o.customType===c&&o.details?.nodeId===e&&g(o)===u))throw new Error(`Pi did not materialize the context baseline for ${e}`);await T(e,i.snapshot,i.loads),await h(a)})}s(_,"registerCanvasContextIntro");var z=_;export{c as CONTEXT_INTRO_CUSTOM_TYPE,A as buildContextIntro,j as buildForkContextIntro,z as default,_ as registerCanvasContextIntro};
+var w=Object.defineProperty;var s=(t,e)=>w(t,"name",{value:e,configurable:!0});import{envNodeId as b}from"../shared/env.js";import{CONTEXT_INTRO_CUSTOM_TYPE as a,formatCard as C}from"../shared/generated-context.js";import{brokerDelivery as m,brokerExtensionState as f}from"../core/runtime/broker/daemon-ops.js";import{buildForkBearingsFromState as p}from"../core/runtime/broker-extension-render.js";import{acknowledgePersonaBaseline as T}from"../core/runtime/broker-persona-guidance.js";import{situationalContextEnvelope as l}from"../core/runtime/situational-context.js";async function O(t){return(await m(t,{activity:"boot"})).content}s(O,"buildContextIntro");async function P(t){const e=await f(t);return p(e,l(t)??"")}s(P,"buildForkContextIntro");function g(t){const e=t.content;return typeof e=="string"?e:Array.isArray(e)?e.filter(r=>typeof r?.text=="string").map(r=>r.text).join(`
+`):""}s(g,"entryText");function v(t){t.on("session_start",async(e,r)=>{const n=b();if(n===void 0||n.trim()==="")return;const x=e?.reason,i=await f(n);if(i.warm_spare||x==="new"&&i.node.parent===null)return;const c=r.sessionManager.getBranch().filter(o=>o.type==="custom_message"&&o.customType===a);if(c.some(o=>o.details?.nodeId===n||g(o).includes(n)))return;const d=await m(n,{activity:"boot",inherited:c.length>0}),y=d.inherited===!0?p(i,l(n)??""):d.content,u=C("bearings",{},y);if(t.sendMessage({customType:a,content:u,display:!0,details:{nodeId:n}}),!r.sessionManager.getBranch().some(o=>o.type==="custom_message"&&o.customType===a&&o.details?.nodeId===n&&g(o)===u))throw new Error(`Pi did not materialize the context baseline for ${n}`);await T(i)})}s(v,"registerCanvasContextIntro");var S=v;export{a as CONTEXT_INTRO_CUSTOM_TYPE,O as buildContextIntro,P as buildForkContextIntro,S as default,v as registerCanvasContextIntro};

package/dist/pi-extensions/canvas-doc-substrate.d.ts

@@ -42,7 +42,6 @@ type ToolCallResultLike = {
 } | void;
 interface PiLike {
     on(event: 'before_agent_start', handler: (event: BeforeAgentStartEventLike) => BeforeAgentStartResultLike | void | Promise<BeforeAgentStartResultLike | void>): void;
-    on(event: 'session_start', handler: (event: unknown, ctx: unknown) => void | Promise<void>): void;
     on(event: 'session_compact', handler: (event: unknown, ctx: unknown) => void | Promise<void>): void;
     on(event: 'turn_end', handler: (event: unknown, ctx: unknown) => void | Promise<void>): void;
     on(event: 'tool_call', handler: (event: ToolCallEventLike, ctx: unknown) => ToolCallResultLike | Promise<ToolCallResultLike>): void;

package/dist/pi-extensions/canvas-doc-substrate.js

@@ -1,9 +1,9 @@
-var E=Object.defineProperty;var l=(n,e)=>E(n,"name",{value:e,configurable:!0});import{envNodeId as g}from"../shared/env.js";import{homedir as C}from"node:os";import{join as S,resolve as _}from"node:path";import{brokerContext as O,brokerContextEvent as f,commitBrokerContext as p}from"../core/runtime/broker/daemon-ops.js";import{clearSessionCache as L}from"../core/substrate/session-cache.js";import{contextExposureStatesEqual as N,mergeContextExposureState as k,replaceContextExposureState as x,restoreContextExposure as h,sharedContextExposureState as P,snapshotContextExposure as T}from"../core/substrate/injected-store.js";import{autoLoadedContextInner as $,mergeAutoLoadedContext as H}from"./envelope-merge.js";const I=`
+var y=Object.defineProperty;var c=(n,e)=>y(n,"name",{value:e,configurable:!0});import{envNodeId as p}from"../shared/env.js";import{homedir as b}from"node:os";import{join as w,resolve as g}from"node:path";import{brokerDelivery as m}from"../core/runtime/broker/daemon-ops.js";import{autoLoadedContextInner as x,mergeAutoLoadedContext as O}from"./envelope-merge.js";const _=`
 
-Guidelines:`;function R(n){const e=n?.command;return typeof e=="string"&&e.trim()!==""?e:null}l(R,"bashCommandOf");function j(n){return["HELD \u2014 nothing ran.","","Your bash command was NOT executed. It matched memory you had not yet read, and that memory is below.","","Read it, then re-issue your WHOLE command unchanged \u2014 every clause of it, including any heredoc, redirect, or `$(\u2026)` that built its input, because none of that ran either. The re-issue executes: this memory is now in your transcript, so there is nothing left to deliver and nothing left to hold.","",n].join(`
-`)}l(j,"heldReason");const A=["HELD \u2014 nothing ran.","","Your bash command was NOT executed. Another command in this same message was held against memory you had not read, and that memory was returned with it.","","Read it, then re-issue your WHOLE command unchanged. The re-issue executes."].join(`
-`);function D(n){const e=g();if(e===void 0||e.trim()==="")return;const s=P(e);n.on("session_start",()=>{L()}),n.on("before_agent_start",async t=>{const a=s.preferenceSnapshot===null,o=await O(e,"preferences"),i=h(o.snapshot);k(s,i);const r=s.preferenceSnapshot;if(r===null)throw new Error(`daemon returned no preference snapshot for ${e}`);if((a||!N(s,i))&&await p(e,T(s),o.loads),r==="")return;const c=t.systemPrompt.indexOf(I);return c===-1?{systemPrompt:`${t.systemPrompt}
+Guidelines:`;function L(n){const e=n?.command;return typeof e=="string"&&e.trim()!==""?e:null}c(L,"bashCommandOf");function N(n){return["HELD \u2014 nothing ran.","","Your bash command was NOT executed. It matched memory you had not yet read, and that memory is below.","","Read it, then re-issue your WHOLE command unchanged \u2014 every clause of it, including any heredoc, redirect, or `$(\u2026)` that built its input, because none of that ran either. The re-issue executes: this memory is now in your transcript, so there is nothing left to deliver and nothing left to hold.","",n].join(`
+`)}c(N,"heldReason");const E=["HELD \u2014 nothing ran.","","Your bash command was NOT executed. Another command in this same message was held against memory you had not read, and that memory was returned with it.","","Read it, then re-issue your WHOLE command unchanged. The re-issue executes."].join(`
+`);function j(n){const e=p();if(e===void 0||e.trim()==="")return;n.on("before_agent_start",async t=>{const o=(await m(e,{activity:"system-prompt"})).content;if(o==="")return;const r=t.systemPrompt.indexOf(_);return r===-1?{systemPrompt:`${t.systemPrompt}
 
-${r}`}:{systemPrompt:`${t.systemPrompt.slice(0,c)}
+${o}`}:{systemPrompt:`${t.systemPrompt.slice(0,r)}
 
-${r}${t.systemPrompt.slice(c)}`}});let u=!1;n.on("turn_end",()=>{u=!1}),n.on("session_compact",async()=>{const t=await f(e,"compact");await p(e,t.snapshot,t.loads),x(s,h(t.snapshot)),u=!1}),n.on("tool_call",async t=>{if(t.toolName!=="bash")return;const a=R(t.input);if(a===null)return;if(u)return{block:!0,reason:A};const o=await f(e,"pre-command",a),i=o.content;if(i!=="")return u=!0,await p(e,o.snapshot,o.loads),x(s,h(o.snapshot)),{block:!0,reason:j(i)}}),n.on("tool_result",async(t,a)=>{if(t.isError===!0)return;let o=null,i=null;if(t.toolName==="read"){const d=t.input,m=d?.path??d?.file_path;if(m===void 0||m==="")return;const w=typeof a?.cwd=="string"&&a.cwd!==""?a.cwd:process.cwd(),b=m.startsWith("~")?S(C(),m.slice(1)):m;o=_(w,b)}else if(t.toolName==="bash"){const d=t.input;if(typeof d?.command!="string"||d.command.trim()==="")return;i=d.command}else return;const r=await f(e,o!==null?"read":"command",o??i),c=r.content;if(c==="")return;const y=$(c);if(y===null)throw new Error("substrate renderer returned an invalid auto-loaded context block");return await p(e,r.snapshot,r.loads),x(s,h(r.snapshot)),{content:H([y],t.content)}})}l(D,"registerCanvasDocSubstrate");var K=D;export{K as default,D as registerCanvasDocSubstrate};
+${o}${t.systemPrompt.slice(r)}`}});let i=!1;n.on("turn_end",()=>{i=!1}),n.on("session_compact",async()=>{await m(e,{activity:"compact"}),i=!1}),n.on("tool_call",async t=>{if(t.toolName!=="bash")return;const o=L(t.input);if(o===null)return;if(i)return{block:!0,reason:E};const r=(await m(e,{activity:"pre-command",subject:o})).content;if(r!=="")return i=!0,{block:!0,reason:N(r)}}),n.on("tool_result",async(t,o)=>{if(t.isError===!0)return;let r=null,d=null;if(t.toolName==="read"){const a=t.input,s=a?.path??a?.file_path;if(s===void 0||s==="")return;const f=typeof o?.cwd=="string"&&o.cwd!==""?o.cwd:process.cwd(),h=s.startsWith("~")?w(b(),s.slice(1)):s;r=g(f,h)}else if(t.toolName==="bash"){const a=t.input;if(typeof a?.command!="string"||a.command.trim()==="")return;d=a.command}else return;const u=(await m(e,r!==null?{activity:"file-read",subject:r}:{activity:"command",subject:d})).content;if(u==="")return;const l=x(u);if(l===null)throw new Error("substrate renderer returned an invalid auto-loaded context block");return{content:O([l],t.content)}})}c(j,"registerCanvasDocSubstrate");var C=j;export{C as default,j as registerCanvasDocSubstrate};

package/dist/pi-extensions/canvas-inbox-watcher.js

@@ -1,2 +1,2 @@
-var A=Object.defineProperty;var l=(s,t)=>A(s,"name",{value:t,configurable:!0});import{envNodeId as D,envProfileId as H,envWatcherDebounceMs as T,envWatcherTickMs as q}from"../shared/env.js";import{coalesceBrokerInbox as U,entryCards as B}from"../core/runtime/broker/inbox.js";import{acknowledgeBrokerMail as J,claimBrokerMail as $,brokerExtensionState as W}from"../core/runtime/broker/daemon-ops.js";import{wasTurnRefused as G}from"../core/runtime/broker/extension-abort.js";import{isDaemonTransportApiError as R}from"../api/errors.js";import{announceMessageOrigin as X,messageSignature as b}from"../core/runtime/stamp/channel.js";import{captureGoalIfAbsent as j,generateAndCommitInitialName as L}from"./broker-local.js";import{emitEvent as V}from"../core/events/emit.js";import{errorClassFromError as z}from"../core/events/errors.js";import{operationIdContext as p}from"../core/events/operation-id.js";import{situationalContextEnvelope as Q,SITUATIONAL_CONTEXT_CUSTOM_TYPE as _}from"../core/runtime/situational-context.js";import{isProfilePaused as Y}from"../core/profiles/manifest.js";import{brokerIdleTurnStart as K,brokerRunTurnBusy as Z,HELD_DEFERRED_INBOX_PROMPT_JOIN as ee}from"../core/runtime/broker/held-deferred-inbox.js";const v=64,S=16;let m,te=0;class O extends Error{static{l(this,"WatcherFatalError")}constructor(t,e){super(t,{cause:e}),this.name="WatcherFatalError"}}function ie(){return{tickMs:q(),debounceMs:T()}}l(ie,"resolveCadence");function I(){const s=D();return s===void 0||s.trim()===""?void 0:s}l(I,"currentNodeId");function P(){const s=H();return s!==void 0&&s!==""&&Y(s)}l(P,"profilePaused");function E(s){try{return z(s)}catch{return{class:"unknown"}}}l(E,"safeErrorClass");function w(s){try{V(s)}catch{}}l(w,"emitBestEffort");function C(s){try{p.fresh(t=>{w({...s,operation_id:t})})}catch{}}l(C,"emitFreshBestEffort");function x(s,t){try{p.run(s,()=>{w({...t,operation_id:s})})}catch{}}l(x,"emitStoredBestEffort");function ne(s){return s.kind==="human"?{type:"human"}:{type:"runtime",kind:"inbox",entries:s.entries.map(t=>({...t.from===null?{}:{from:t.from},...t.from_name===void 0?{}:{fromName:t.from_name},kind:t.kind,tier:t.tier,...t.ref===void 0?{}:{ref:t.ref}}))}}l(ne,"deliveryOrigin");function F(s,t){if(s.length===0)throw new Error(`cannot create an empty ${t} delivery`);const e=[...new Set(s.map(n=>n.operation_id))].sort(),i=e.length-S;return{channel:t,entryIds:s.map(n=>n.entry_id),throughEntryId:s.at(-1).entry_id,sourceOperationIds:e.slice(0,S),...i>0?{sourceOperationIdsOmitted:i}:{}}}l(F,"deliveryFacts");function y(s){return{channel:s.channel,entry_ids:s.entryIds,through_entry_id:s.throughEntryId,source_operation_ids:s.sourceOperationIds,...s.sourceOperationIdsOmitted===void 0?{}:{source_operation_ids_omitted:s.sourceOperationIdsOmitted}}}l(y,"deliveryFields");function re(s){x(s.operationId,{level:"info",event:"inbox.delivery.completed",outcome:"succeeded",fields:y(s)})}l(re,"emitDeliveryCompleted");function M(s,t,e,i){x(s,{level:"error",event:"inbox.delivery.failed",outcome:"failed",error:i,error_class:E(i),fields:{stage:e,...y(t)}})}l(M,"emitDeliveryFailure");function k(s,t){x(s.operationId,{level:"error",event:"inbox.delivery.failed",outcome:"failed",error_class:{class:"unknown"},fields:{stage:"abandoned",reason:t,...y(s)}})}l(k,"emitDeliveryAbandoned");function se(s){return typeof s=="string"?s:Array.isArray(s)?s.filter(t=>typeof t=="object"&&t!==null&&typeof t.text=="string").map(t=>t.text).join(`
-`):""}l(se,"messageText");function N(s){return s==="quit"||s==="reload"||s==="new"||s==="resume"||s==="fork"}l(N,"isSessionShutdownReason");function ae(s){switch(s){case"quit":return"shutdown";case"reload":case"new":case"resume":case"fork":return"reload";default:return s}}l(ae,"disposalReasonForShutdown");function de(s){return typeof s=="string"?s.slice(0,128):s===null?"null":s===void 0?"undefined":typeof s=="number"||typeof s=="boolean"||typeof s=="bigint"?String(s).slice(0,128):typeof s}l(de,"boundedRuntimeReason");class oe{static{l(this,"CanvasInboxWatcher")}pi;cadence;generation;timer;armed=!1;lastCtx;streaming=!1;runNode=!!process.env.CRTR_RUN_ID;nodeId;claims=new Map;tickInFlight;buffer=[];lastArrival=0;pendingHandoffs=[];pendingCommit;promptJoinInFlight=!1;replayUnseenInherited=!1;seeded=!1;disposed=!1;disposalReason;fatalError;fatalEscaped=!1;constructor(t,e,i){this.pi=t,this.cadence=e,this.generation=i}start(){const t=l((e,i)=>{this.canMutate()&&this.captureCtx(e,i)},"capture");this.pi.on("session_start",(e,i)=>{this.canMutate()&&(this.captureCtx(e,i),this.arm())}),this.pi.on("turn_end",t),this.pi.on("agent_start",(e,i)=>{this.canMutate()&&(this.captureCtx(e,i),this.streaming=!0)}),this.pi.on("agent_end",(e,i)=>{this.canMutate()&&(this.captureCtx(e,i),this.streaming=!1)}),this.pi.on("message_end",e=>{if(!this.canMutate())return;const i=e?.message;if(i?.role!=="user"&&i?.role!=="custom"||!this.pendingHandoffs.some(a=>a.awaitingDequeue!==void 0))return;const n=b(se(i.content)),r=this.pendingHandoffs.find(a=>a.awaitingDequeue===n);r!==void 0&&delete r.awaitingDequeue}),this.pi.on("agent_settled",async(e,i)=>{if(!this.canMutate())return;this.captureCtx(e,i);const n=I();if(n!==void 0)try{this.assertNodeOwnership(n,"settle"),await this.tickInFlight,this.seeded||await this.claimMail(n);const r=await this.settle(n,i,!1,!0);r==="refresh_held"&&this.dispose("refresh",!1),this.runNode&&r==="settled"&&this.canMutate()&&this.buffer.length>0&&this.flushOrdinary(n)}catch(r){this.dispose("shutdown",!1,void 0,{error:r,stage:"settle"})}}),this.pi.on("session_shutdown",async e=>{if(!this.canMutate())return;let i;try{i=e?.reason}catch{i=void 0}const n=N(i)?ae(i):"reload";N(i)||C({level:"warn",event:"inbox.lifecycle.unknown_shutdown_reason",outcome:"failed",fields:{reason:de(i)}});try{await this.disposeAtSettlement(n,this.lastCtx)}catch(r){this.dispose(n,!1,void 0,{error:r,stage:"settle"})}})}arm(){this.armed||(this.armed=!0,this.timer=setInterval(()=>this.runTick(),this.cadence.tickMs),typeof this.timer.unref=="function"&&this.timer.unref(),this.runTick("schedule"))}async disposeAtSettlement(t,e){const i=I();if(i===void 0){this.dispose(t,!1);return}try{this.assertNodeOwnership(i,"settle");const n=await this.settle(i,e,t!=="refresh");this.dispose(n==="refresh_held"?"refresh":t,!1)}catch(n){this.dispose(t,!1,void 0,{error:n,stage:"settle"})}}dispose(t,e,i,n){if(this.disposed)return;this.disposed=!0,this.disposalReason=t,this.clearTimer();const r=n;{const a=[...new Set([...this.pendingCommit?.handoffs??[],...this.pendingHandoffs.splice(0)])];this.buffer.length=0,this.claims.clear(),this.pendingCommit=void 0,this.promptJoinInFlight=!1,this.replayUnseenInherited=!1,this.nodeId=void 0,this.lastCtx=void 0,this.lastArrival=0,this.streaming=!1,this.seeded=!1,this.ownsCurrentGeneration()&&(m=void 0);for(const d of a)k(d,t)}if(r!==void 0){this.scheduleHandlerFatal(r.error,r.stage);return}}ownsCurrentGeneration(){return m===this&&m.generation===this.generation}canMutate(){return this.ownsCurrentGeneration()&&!this.disposed&&this.fatalError===void 0}captureCtx(t,e){e!==void 0&&(this.lastCtx=e)}clearTimer(){this.timer!==void 0&&(clearInterval(this.timer),this.timer=void 0)}isIdle(){if(this.runNode&&Z())return!1;try{if(typeof this.lastCtx?.isIdle=="function")return this.lastCtx.isIdle()===!0}catch{}return!this.streaming}assertNodeOwnership(t,e){!this.seeded||this.nodeId===void 0||this.nodeId===t||this.raiseReadFatal(e,new Error(`watcher node changed from ${this.nodeId} to ${t}`))}raiseFatal(t,e,i,n){throw this.fatalError===void 0&&(this.fatalError=new O(e,i),this.clearTimer(),C({level:"error",event:t,outcome:"failed",error:i,error_class:E(i),fields:n})),this.fatalError}raiseReadFatal(t,e){return this.raiseFatal("inbox.read.failed",`inbox ${t} state is corrupt`,e,{stage:t})}raiseSituationalFatal(t,e){return this.raiseFatal("inbox.situational_context.missing","situational context marker has no readable sidecar",e,{entry_id:t})}escapeFatal(t,e){if(!this.fatalEscaped){if(this.fatalEscaped=!0,e==="throw")throw t;queueMicrotask(()=>{throw t})}}scheduleHandlerFatal(t,e){let i;if(t instanceof O)i=t;else try{this.raiseReadFatal(e,t)}catch(n){i=n}this.escapeFatal(i,"schedule")}runTick(t="throw"){if(!this.canMutate()||this.tickInFlight!==void 0)return;const e=this.tick().catch(i=>{if(this.canMutate()){if(R(i)){C({level:"warn",event:"inbox.read.failed",outcome:"failed",error:i,error_class:E(i),fields:{stage:"poll"}});return}this.scheduleHandlerFatal(i,"poll")}}).finally(()=>{this.tickInFlight===e&&(this.tickInFlight=void 0)});this.tickInFlight=e}async claimMail(t){this.assertNodeOwnership(t,"poll");let e;try{e=await $(t,"wake")}catch(a){throw R(a)&&(this.replayUnseenInherited=!0),a}if(!this.canMutate()||e.action==="hold")return!1;const i=this.replayUnseenInherited;this.replayUnseenInherited=!1,this.nodeId=t,this.seeded=!0;const n=new Set(e.deliveries.map(a=>a.entry.entry_id)),r=this.buffer.filter(a=>!n.has(a.entry_id));for(const a of r)this.claims.delete(a.entry_id);this.buffer.splice(0,this.buffer.length,...this.buffer.filter(a=>n.has(a.entry_id)));for(const a of e.deliveries){const d=a.entry.entry_id;this.claims.has(d)||(this.claims.set(d,a),a.handoff==="inherited"&&!i?p.fresh(f=>{this.pendingHandoffs.push({...F([a.entry],"visible"),operationId:f,settleAtAgentSettled:!0})}):(this.buffer.push(a.entry),this.lastArrival=Date.now()))}return!0}async tick(){const t=I();if(t!==void 0){if(this.pendingCommit!==void 0){await this.retryPendingCommit(t)==="refresh_held"&&this.canMutate()&&this.dispose("refresh",!1);return}this.promptJoinInFlight||P()||this.pendingHandoffs.length>=v||await this.claimMail(t)&&this.buffer.length>0&&(!this.runNode||this.isIdle()||this.buffer.some(e=>e.tier==="critical"))&&Date.now()-this.lastArrival>=this.cadence.debounceMs&&this.flushOrdinary(t)}}missingChannelEntries(t){const e=t.filter(r=>this.claims.has(r.entry_id)),i=this.coveredEntryIds("hidden"),n=this.coveredEntryIds("visible");return{hiddenEntries:e.filter(r=>(r.data?.situational===!0||r.data?.situationalOnly===!0)&&!i.has(r.entry_id)),visibleEntries:e.filter(r=>r.data?.situationalOnly!==!0&&!n.has(r.entry_id))}}visibleRoute(t){return t.length===0?"none":this.isIdle()?"idle":this.runNode?t.some(e=>e.tier==="critical")?"critical":"none":t.some(e=>e.tier==="critical")?"critical":t.some(e=>e.tier==="urgent"||e.kind==="final")?"steer":"followUp"}buildPlan(t){const{hiddenEntries:e,visibleEntries:i}=this.missingChannelEntries(t),n=new Set(e.map(u=>u.entry_id)),r=new Set(i.map(u=>u.entry_id)),a=t.filter(u=>n.has(u.entry_id)||r.has(u.entry_id)),d=this.isIdle()&&a.length>0&&a.every(u=>u.tier==="deferred"),f=this.visibleRoute(i)==="critical",o=!d&&!f&&e.length>0,c=!d&&!f&&i.length>0;return{hiddenEntries:e,visibleEntries:i,deferredHold:d,sendCount:Number(o)+Number(c)}}ordinaryPlan(){return this.buildPlan(this.buffer)}contextCards(t,e){const i=[];if(e.some(n=>n.data?.situational===!0)){const n=e.at(-1).entry_id;let r;try{r=Q(t)}catch(a){this.raiseSituationalFatal(n,a)}r===null&&this.raiseSituationalFatal(n,new Error(`missing situational context for entry ${n}`)),i.push(r)}for(const n of e)n.data?.situationalOnly===!0&&i.push(...B(n));return i}digest(t,e){try{return U(t)}catch(i){this.raiseReadFatal(e,i)}}sendDelivery(t,e,i,n,r){this.pendingHandoffs.length>=v&&this.raiseReadFatal(n,new Error(`pending handoff capacity exceeded before ${t} send`));let a;try{a=F(e,t)}catch(o){this.raiseReadFatal(n,o)}let d;try{p.fresh(o=>{d=o,w({level:"info",event:"inbox.delivery.started",operation_id:o,fields:y(a)}),i()})}catch(o){return d===void 0&&this.raiseReadFatal(n,o),M(d,a,"send",o),"failed"}d===void 0&&this.raiseReadFatal(n,new Error(`${t} delivery returned without an operation id`));const f={operationId:d,...a,...r===void 0?{}:{awaitingDequeue:r}};return this.canMutate()?(this.pendingHandoffs.push(f),"handed-off"):(this.disposed&&this.disposalReason!==void 0&&k(f,this.disposalReason),"inactive")}sendContext(t,e,i,n,r,a){const d=n==="steer"||n==="followUp"?n:this.isIdle()?void 0:"followUp",f=d===void 0||i.length===0?void 0:b(i.at(-1));return this.sendDelivery("hidden",e,()=>{this.runNode&&r&&this.pi.appendEntry("crtr-turn-input",{message_ids:e.map(o=>o.entry_id)}),i.forEach((o,c)=>{const u=r&&c===i.length-1;this.pi.sendMessage({customType:_,content:o,display:!0,details:{nodeId:t}},d!==void 0?{deliverAs:d}:u?{deliverAs:"followUp",triggerTurn:!0}:{})})},a,f)}sendVisible(t,e,i,n,r,a){return this.sendDelivery("visible",t,()=>{if(r!=="idle"&&r!=="steer"&&r!=="followUp")throw new Error(`visible send requested for non-send route ${r}`);for(const d of e)this.pi.sendMessage({customType:_,content:d,display:!0},r==="idle"?{}:{deliverAs:r});if(X(i,n),r==="idle"){const d=K();if(d===void 0)throw new Error("broker idle-turn admission is unavailable");d(i,this.runNode?t.map(f=>f.entry_id):[])}else this.pi.sendUserMessage(i,{deliverAs:r})},a,r==="steer"||r==="followUp"?b(i):void 0)}abortCritical(){try{this.lastCtx?.abort?.()}catch{}}requeueFromBatch(t,e){if(e.size===0)return;const i=t.filter(a=>e.has(a.entry_id)),n=new Set(i.map(a=>a.entry_id)),r=this.buffer.filter(a=>!n.has(a.entry_id));this.buffer.splice(0,this.buffer.length,...i,...r)}executePlan(t,e,i){const n=new Set,r=this.visibleRoute(e.visibleEntries);if(r==="critical"){if(this.abortCritical(),!this.canMutate())return{inactive:!0,requeueEntryIds:n};for(const o of e.visibleEntries)n.add(o.entry_id);for(const o of e.hiddenEntries)n.add(o.entry_id);return{inactive:!1,requeueEntryIds:n}}if(this.runNode&&r==="none")return{inactive:!1,requeueEntryIds:new Set([...e.hiddenEntries,...e.visibleEntries].map(o=>o.entry_id))};const a=e.visibleEntries.length>0?this.digest(e.visibleEntries,i):[],[d,...f]=a;for(const o of f)for(const c of o.entries)n.add(c.entry_id);if(e.hiddenEntries.length>0){const o=this.contextCards(t,e.hiddenEntries),c=this.sendContext(t,e.hiddenEntries,o,r,d===void 0,i);if(c==="inactive")return{inactive:!0,requeueEntryIds:n};if(c==="failed")for(const u of e.hiddenEntries)n.add(u.entry_id)}if(!this.canMutate())return{inactive:!0,requeueEntryIds:n};if(d!==void 0){const o=this.sendVisible(d.entries,d.cards,d.text,ne(d),r,i);if(o==="inactive")return{inactive:!0,requeueEntryIds:n};if(o==="failed")for(const c of d.entries)n.add(c.entry_id);else d.kind==="human"&&(j(t,d.text),L(t,d.text))}return{inactive:!1,requeueEntryIds:n}}flushOrdinary(t){if(this.buffer.length===0)return"empty";const e=this.ordinaryPlan();if(e.deferredHold)return"held";if(this.pendingHandoffs.length+e.sendCount>v)return"capacity-blocked";const i=[...this.buffer],n=this.executePlan(t,e,"poll");return n.inactive||(this.buffer.splice(0,i.length),this.requeueFromBatch(i,n.requeueEntryIds)),"attempted"}async prependHeldDeferredInbox(t){if(!this.canMutate()||this.nodeId===void 0||P())return;const e=this.ordinaryPlan();if(!e.deferredHold)return;const i=e.visibleEntries.length===0?[]:this.digest(e.visibleEntries,"poll"),n=+(e.hiddenEntries.length>0)+i.length;if(this.pendingHandoffs.length+n>v)return;const r=[...this.buffer];this.promptJoinInFlight=!0;try{this.runNode&&this.pi.appendEntry("crtr-turn-input",{message_ids:[...e.hiddenEntries,...e.visibleEntries].map(a=>a.entry_id)}),e.hiddenEntries.length>0&&await this.sendPromptJoinDelivery(t,"hidden",e.hiddenEntries,this.contextCards(this.nodeId,e.hiddenEntries));for(const a of i)await this.sendPromptJoinDelivery(t,"visible",a.entries,[...a.cards,a.text]);if(!this.canMutate())return;this.buffer.splice(0,r.length)}finally{this.promptJoinInFlight=!1}}async sendPromptJoinDelivery(t,e,i,n){let r;try{r=F(i,e)}catch(f){this.raiseReadFatal("poll",f)}let a;try{await p.fresh(async f=>{a=f,w({level:"info",event:"inbox.delivery.started",operation_id:f,fields:y(r)});for(const o of n)await t.sendCustomMessage({customType:_,content:o,display:!0})})}catch(f){throw a===void 0&&this.raiseReadFatal("poll",f),M(a,r,"send",f),f}a===void 0&&this.raiseReadFatal("poll",new Error(`${e} prompt-join delivery returned without an operation id`));const d={operationId:a,...r,settleAtAgentSettled:!0};if(!this.canMutate()){this.disposed&&this.disposalReason!==void 0&&k(d,this.disposalReason);return}this.pendingHandoffs.push(d)}coveredEntryIds(t){const e=new Set;for(const i of this.pendingHandoffs)if(i.channel===t)for(const n of i.entryIds)e.add(n);return e}retryPendingCommit(t){const e=this.pendingCommit;if(e===void 0)return Promise.resolve("settled");if(e.attempt!==void 0)return e.attempt;const i=this.attemptPendingCommit(t,e).finally(()=>{e.attempt===i&&(e.attempt=void 0)});return e.attempt=i,i}async attemptPendingCommit(t,e){let i=!1;try{const r=await J(t,e.receipts);if(r.action==="hold")return"refresh_held";for(const a of e.receipts){const d=r.results.find(f=>f.delivery_id===a.delivery_id);if(d?.outcome!==a.disposition&&d?.outcome!=="stale")throw new Error("daemon returned no terminal mail settlement outcome")}i=r.results.every(a=>a.outcome==="acknowledged")}catch(r){if(this.pendingCommit===e)for(const a of e.handoffs)M(a.operationId,a,"receipt_commit",r);return"held"}if(this.pendingCommit!==e)return"settled";for(const r of e.entryIds)this.claims.delete(r);if(e.receipts.some(r=>r.disposition==="released")){const r=new Set(e.entryIds);this.buffer.splice(0,this.buffer.length,...this.buffer.filter(a=>!r.has(a.entry_id)))}this.pendingCommit=void 0;const n=this.detachPending(r=>r.entryIds.every(a=>!this.claims.has(a)));for(const r of n)i&&re(r);return"settled"}async settle(t,e,i,n=!1){if(i)try{if(e?.hasPendingMessages?.()===!0)return"held"}catch{}if(this.pendingCommit!==void 0)return this.retryPendingCommit(t);const r=G(),a=!r&&this.pendingHandoffs.some(h=>h.awaitingDequeue!==void 0)&&await this.nodeRefreshing(t);if(this.pendingCommit!==void 0)return this.retryPendingCommit(t);const d=new Set(this.buffer.map(h=>h.entry_id)),f=new Set(a?this.pendingHandoffs.filter(h=>h.awaitingDequeue!==void 0).flatMap(h=>[...h.entryIds]):[]),o=this.pendingHandoffs.filter(h=>(n||h.settleAtAgentSettled!==!0)&&h.entryIds.every(g=>!f.has(g))),c=new Set(o.flatMap(h=>[...h.entryIds])),u=[...this.claims.keys()].filter(h=>r||c.has(h)&&!d.has(h));return u.length===0?"settled":(this.pendingCommit={handoffs:o,entryIds:u,receipts:u.map(h=>{const g=this.claims.get(h);return{delivery_id:g.delivery_id,attempts:g.attempts,disposition:r?"released":"acknowledged"}})},this.retryPendingCommit(t))}async nodeRefreshing(t){try{return(await W(t)).node.intent==="refresh"}catch{return!0}}detachPending(t){const e=[];for(let i=this.pendingHandoffs.length-1;i>=0;i-=1){const n=this.pendingHandoffs[i];t(n)&&e.push(...this.pendingHandoffs.splice(i,1))}return e.reverse(),e}}function fe(s,t){m?.dispose("reload",!1);const e=new oe(s,t,++te);m=e;const i=l(n=>e.prependHeldDeferredInbox(n),"promptJoin");globalThis[ee]=i;try{e.start()}catch(n){throw e.dispose("reload",!1),n}return e}l(fe,"installWatcher");function le(s){const t=fe(s,ie());return()=>t.dispose("shutdown",!1)}l(le,"registerCanvasInboxWatcher");var xe=le;export{xe as default,le as registerCanvasInboxWatcher};
+var H=Object.defineProperty;var l=(s,t)=>H(s,"name",{value:t,configurable:!0});import{envInboxBetweenTurns as N,envNodeId as D,envProfileId as T,envWatcherDebounceMs as q,envWatcherTickMs as U}from"../shared/env.js";import{coalesceBrokerInbox as B,entryCards as J}from"../core/runtime/broker/inbox.js";import{acknowledgeBrokerMail as $,claimBrokerMail as W,brokerExtensionState as G}from"../core/runtime/broker/daemon-ops.js";import{wasTurnRefused as X}from"../core/runtime/broker/extension-abort.js";import{isDaemonTransportApiError as R}from"../api/errors.js";import{announceMessageOrigin as j,messageSignature as b}from"../core/runtime/stamp/channel.js";import{captureGoalIfAbsent as L,generateAndCommitInitialName as V}from"./broker-local.js";import{emitEvent as z}from"../core/events/emit.js";import{errorClassFromError as Q}from"../core/events/errors.js";import{operationIdContext as p}from"../core/events/operation-id.js";import{situationalContextEnvelope as Y,SITUATIONAL_CONTEXT_CUSTOM_TYPE as _}from"../core/runtime/situational-context.js";import{isProfilePaused as K}from"../core/profiles/manifest.js";import{brokerIdleTurnStart as Z,brokerRunTurnBusy as ee,HELD_DEFERRED_INBOX_PROMPT_JOIN as te}from"../core/runtime/broker/held-deferred-inbox.js";const v=64,S=16;let m,ie=0;class O extends Error{static{l(this,"WatcherFatalError")}constructor(t,e){super(t,{cause:e}),this.name="WatcherFatalError"}}function ne(){return{tickMs:U(),debounceMs:q()}}l(ne,"resolveCadence");function I(){const s=D();return s===void 0||s.trim()===""?void 0:s}l(I,"currentNodeId");function P(){const s=T();return s!==void 0&&s!==""&&K(s)}l(P,"profilePaused");function E(s){try{return Q(s)}catch{return{class:"unknown"}}}l(E,"safeErrorClass");function w(s){try{z(s)}catch{}}l(w,"emitBestEffort");function C(s){try{p.fresh(t=>{w({...s,operation_id:t})})}catch{}}l(C,"emitFreshBestEffort");function x(s,t){try{p.run(s,()=>{w({...t,operation_id:s})})}catch{}}l(x,"emitStoredBestEffort");function re(s){return s.kind==="human"?{type:"human"}:{type:"runtime",kind:"inbox",entries:s.entries.map(t=>({...t.from===null?{}:{from:t.from},...t.from_name===void 0?{}:{fromName:t.from_name},kind:t.kind,tier:t.tier,...t.ref===void 0?{}:{ref:t.ref}}))}}l(re,"deliveryOrigin");function F(s,t){if(s.length===0)throw new Error(`cannot create an empty ${t} delivery`);const e=[...new Set(s.map(n=>n.operation_id))].sort(),i=e.length-S;return{channel:t,entryIds:s.map(n=>n.entry_id),throughEntryId:s.at(-1).entry_id,sourceOperationIds:e.slice(0,S),...i>0?{sourceOperationIdsOmitted:i}:{}}}l(F,"deliveryFacts");function y(s){return{channel:s.channel,entry_ids:s.entryIds,through_entry_id:s.throughEntryId,source_operation_ids:s.sourceOperationIds,...s.sourceOperationIdsOmitted===void 0?{}:{source_operation_ids_omitted:s.sourceOperationIdsOmitted}}}l(y,"deliveryFields");function se(s){x(s.operationId,{level:"info",event:"inbox.delivery.completed",outcome:"succeeded",fields:y(s)})}l(se,"emitDeliveryCompleted");function M(s,t,e,i){x(s,{level:"error",event:"inbox.delivery.failed",outcome:"failed",error:i,error_class:E(i),fields:{stage:e,...y(t)}})}l(M,"emitDeliveryFailure");function k(s,t){x(s.operationId,{level:"error",event:"inbox.delivery.failed",outcome:"failed",error_class:{class:"unknown"},fields:{stage:"abandoned",reason:t,...y(s)}})}l(k,"emitDeliveryAbandoned");function ae(s){return typeof s=="string"?s:Array.isArray(s)?s.filter(t=>typeof t=="object"&&t!==null&&typeof t.text=="string").map(t=>t.text).join(`
+`):""}l(ae,"messageText");function A(s){return s==="quit"||s==="reload"||s==="new"||s==="resume"||s==="fork"}l(A,"isSessionShutdownReason");function de(s){switch(s){case"quit":return"shutdown";case"reload":case"new":case"resume":case"fork":return"reload";default:return s}}l(de,"disposalReasonForShutdown");function oe(s){return typeof s=="string"?s.slice(0,128):s===null?"null":s===void 0?"undefined":typeof s=="number"||typeof s=="boolean"||typeof s=="bigint"?String(s).slice(0,128):typeof s}l(oe,"boundedRuntimeReason");class fe{static{l(this,"CanvasInboxWatcher")}pi;cadence;generation;timer;armed=!1;lastCtx;streaming=!1;runNode=N();nodeId;claims=new Map;tickInFlight;buffer=[];lastArrival=0;pendingHandoffs=[];pendingCommit;promptJoinInFlight=!1;replayUnseenInherited=!1;seeded=!1;disposed=!1;disposalReason;fatalError;fatalEscaped=!1;constructor(t,e,i){this.pi=t,this.cadence=e,this.generation=i}start(){const t=l((e,i)=>{this.canMutate()&&this.captureCtx(e,i)},"capture");this.pi.on("session_start",(e,i)=>{this.canMutate()&&(this.captureCtx(e,i),this.arm())}),this.pi.on("turn_end",t),this.pi.on("agent_start",(e,i)=>{this.canMutate()&&(this.captureCtx(e,i),this.streaming=!0)}),this.pi.on("agent_end",(e,i)=>{this.canMutate()&&(this.captureCtx(e,i),this.streaming=!1)}),this.pi.on("message_end",e=>{if(!this.canMutate())return;const i=e?.message;if(i?.role!=="user"&&i?.role!=="custom"||!this.pendingHandoffs.some(a=>a.awaitingDequeue!==void 0))return;const n=b(ae(i.content)),r=this.pendingHandoffs.find(a=>a.awaitingDequeue===n);r!==void 0&&delete r.awaitingDequeue}),this.pi.on("agent_settled",async(e,i)=>{if(!this.canMutate())return;this.captureCtx(e,i);const n=I();if(n!==void 0)try{this.assertNodeOwnership(n,"settle"),await this.tickInFlight,this.seeded||await this.claimMail(n);const r=await this.settle(n,i,!1,!0);r==="refresh_held"&&this.dispose("refresh",!1),this.runNode&&r==="settled"&&this.canMutate()&&this.buffer.length>0&&this.flushOrdinary(n)}catch(r){this.dispose("shutdown",!1,void 0,{error:r,stage:"settle"})}}),this.pi.on("session_shutdown",async e=>{if(!this.canMutate())return;let i;try{i=e?.reason}catch{i=void 0}const n=A(i)?de(i):"reload";A(i)||C({level:"warn",event:"inbox.lifecycle.unknown_shutdown_reason",outcome:"failed",fields:{reason:oe(i)}});try{await this.disposeAtSettlement(n,this.lastCtx)}catch(r){this.dispose(n,!1,void 0,{error:r,stage:"settle"})}})}arm(){this.armed||(this.armed=!0,this.timer=setInterval(()=>this.runTick(),this.cadence.tickMs),typeof this.timer.unref=="function"&&this.timer.unref(),this.runTick("schedule"))}async disposeAtSettlement(t,e){const i=I();if(i===void 0){this.dispose(t,!1);return}try{this.assertNodeOwnership(i,"settle");const n=await this.settle(i,e,t!=="refresh");this.dispose(n==="refresh_held"?"refresh":t,!1)}catch(n){this.dispose(t,!1,void 0,{error:n,stage:"settle"})}}dispose(t,e,i,n){if(this.disposed)return;this.disposed=!0,this.disposalReason=t,this.clearTimer();const r=n;{const a=[...new Set([...this.pendingCommit?.handoffs??[],...this.pendingHandoffs.splice(0)])];this.buffer.length=0,this.claims.clear(),this.pendingCommit=void 0,this.promptJoinInFlight=!1,this.replayUnseenInherited=!1,this.nodeId=void 0,this.lastCtx=void 0,this.lastArrival=0,this.streaming=!1,this.seeded=!1,this.ownsCurrentGeneration()&&(m=void 0);for(const d of a)k(d,t)}if(r!==void 0){this.scheduleHandlerFatal(r.error,r.stage);return}}ownsCurrentGeneration(){return m===this&&m.generation===this.generation}canMutate(){return this.ownsCurrentGeneration()&&!this.disposed&&this.fatalError===void 0}captureCtx(t,e){e!==void 0&&(this.lastCtx=e)}clearTimer(){this.timer!==void 0&&(clearInterval(this.timer),this.timer=void 0)}isIdle(){if(this.runNode&&ee())return!1;try{if(typeof this.lastCtx?.isIdle=="function")return this.lastCtx.isIdle()===!0}catch{}return!this.streaming}assertNodeOwnership(t,e){!this.seeded||this.nodeId===void 0||this.nodeId===t||this.raiseReadFatal(e,new Error(`watcher node changed from ${this.nodeId} to ${t}`))}raiseFatal(t,e,i,n){throw this.fatalError===void 0&&(this.fatalError=new O(e,i),this.clearTimer(),C({level:"error",event:t,outcome:"failed",error:i,error_class:E(i),fields:n})),this.fatalError}raiseReadFatal(t,e){return this.raiseFatal("inbox.read.failed",`inbox ${t} state is corrupt`,e,{stage:t})}raiseSituationalFatal(t,e){return this.raiseFatal("inbox.situational_context.missing","situational context marker has no readable sidecar",e,{entry_id:t})}escapeFatal(t,e){if(!this.fatalEscaped){if(this.fatalEscaped=!0,e==="throw")throw t;queueMicrotask(()=>{throw t})}}scheduleHandlerFatal(t,e){let i;if(t instanceof O)i=t;else try{this.raiseReadFatal(e,t)}catch(n){i=n}this.escapeFatal(i,"schedule")}runTick(t="throw"){if(!this.canMutate()||this.tickInFlight!==void 0)return;const e=this.tick().catch(i=>{if(this.canMutate()){if(R(i)){C({level:"warn",event:"inbox.read.failed",outcome:"failed",error:i,error_class:E(i),fields:{stage:"poll"}});return}this.scheduleHandlerFatal(i,"poll")}}).finally(()=>{this.tickInFlight===e&&(this.tickInFlight=void 0)});this.tickInFlight=e}async claimMail(t){this.assertNodeOwnership(t,"poll");let e;try{e=await W(t,"wake")}catch(a){throw R(a)&&(this.replayUnseenInherited=!0),a}if(!this.canMutate()||e.action==="hold")return!1;const i=this.replayUnseenInherited;this.replayUnseenInherited=!1,this.nodeId=t,this.seeded=!0;const n=new Set(e.deliveries.map(a=>a.entry.entry_id)),r=this.buffer.filter(a=>!n.has(a.entry_id));for(const a of r)this.claims.delete(a.entry_id);this.buffer.splice(0,this.buffer.length,...this.buffer.filter(a=>n.has(a.entry_id)));for(const a of e.deliveries){const d=a.entry.entry_id;this.claims.has(d)||(this.claims.set(d,a),a.handoff==="inherited"&&!i?p.fresh(f=>{this.pendingHandoffs.push({...F([a.entry],"visible"),operationId:f,settleAtAgentSettled:!0})}):(this.buffer.push(a.entry),this.lastArrival=Date.now()))}return!0}async tick(){const t=I();if(t!==void 0){if(this.pendingCommit!==void 0){await this.retryPendingCommit(t)==="refresh_held"&&this.canMutate()&&this.dispose("refresh",!1);return}this.promptJoinInFlight||P()||this.pendingHandoffs.length>=v||await this.claimMail(t)&&this.buffer.length>0&&(!this.runNode||this.isIdle()||this.buffer.some(e=>e.tier==="critical"))&&Date.now()-this.lastArrival>=this.cadence.debounceMs&&this.flushOrdinary(t)}}missingChannelEntries(t){const e=t.filter(r=>this.claims.has(r.entry_id)),i=this.coveredEntryIds("hidden"),n=this.coveredEntryIds("visible");return{hiddenEntries:e.filter(r=>(r.data?.situational===!0||r.data?.situationalOnly===!0)&&!i.has(r.entry_id)),visibleEntries:e.filter(r=>r.data?.situationalOnly!==!0&&!n.has(r.entry_id))}}visibleRoute(t){return t.length===0?"none":this.isIdle()?"idle":this.runNode?t.some(e=>e.tier==="critical")?"critical":"none":t.some(e=>e.tier==="critical")?"critical":t.some(e=>e.tier==="urgent"||e.kind==="final")?"steer":"followUp"}buildPlan(t){const{hiddenEntries:e,visibleEntries:i}=this.missingChannelEntries(t),n=new Set(e.map(u=>u.entry_id)),r=new Set(i.map(u=>u.entry_id)),a=t.filter(u=>n.has(u.entry_id)||r.has(u.entry_id)),d=this.isIdle()&&a.length>0&&a.every(u=>u.tier==="deferred"),f=this.visibleRoute(i)==="critical",o=!d&&!f&&e.length>0,c=!d&&!f&&i.length>0;return{hiddenEntries:e,visibleEntries:i,deferredHold:d,sendCount:Number(o)+Number(c)}}ordinaryPlan(){return this.buildPlan(this.buffer)}contextCards(t,e){const i=[];if(e.some(n=>n.data?.situational===!0)){const n=e.at(-1).entry_id;let r;try{r=Y(t)}catch(a){this.raiseSituationalFatal(n,a)}r===null&&this.raiseSituationalFatal(n,new Error(`missing situational context for entry ${n}`)),i.push(r)}for(const n of e)n.data?.situationalOnly===!0&&i.push(...J(n));return i}digest(t,e){try{return B(t)}catch(i){this.raiseReadFatal(e,i)}}sendDelivery(t,e,i,n,r){this.pendingHandoffs.length>=v&&this.raiseReadFatal(n,new Error(`pending handoff capacity exceeded before ${t} send`));let a;try{a=F(e,t)}catch(o){this.raiseReadFatal(n,o)}let d;try{p.fresh(o=>{d=o,w({level:"info",event:"inbox.delivery.started",operation_id:o,fields:y(a)}),i()})}catch(o){return d===void 0&&this.raiseReadFatal(n,o),M(d,a,"send",o),"failed"}d===void 0&&this.raiseReadFatal(n,new Error(`${t} delivery returned without an operation id`));const f={operationId:d,...a,...r===void 0?{}:{awaitingDequeue:r}};return this.canMutate()?(this.pendingHandoffs.push(f),"handed-off"):(this.disposed&&this.disposalReason!==void 0&&k(f,this.disposalReason),"inactive")}sendContext(t,e,i,n,r,a){const d=n==="steer"||n==="followUp"?n:this.isIdle()?void 0:"followUp",f=d===void 0||i.length===0?void 0:b(i.at(-1));return this.sendDelivery("hidden",e,()=>{this.runNode&&r&&this.pi.appendEntry("crtr-turn-input",{message_ids:e.map(o=>o.entry_id)}),i.forEach((o,c)=>{const u=r&&c===i.length-1;this.pi.sendMessage({customType:_,content:o,display:!0,details:{nodeId:t}},d!==void 0?{deliverAs:d}:u?{deliverAs:"followUp",triggerTurn:!0}:{})})},a,f)}sendVisible(t,e,i,n,r,a){return this.sendDelivery("visible",t,()=>{if(r!=="idle"&&r!=="steer"&&r!=="followUp")throw new Error(`visible send requested for non-send route ${r}`);for(const d of e)this.pi.sendMessage({customType:_,content:d,display:!0},r==="idle"?{}:{deliverAs:r});if(j(i,n),r==="idle"){const d=Z();if(d===void 0)throw new Error("broker idle-turn admission is unavailable");d(i,this.runNode?t.map(f=>f.entry_id):[])}else this.pi.sendUserMessage(i,{deliverAs:r})},a,r==="steer"||r==="followUp"?b(i):void 0)}abortCritical(){try{this.lastCtx?.abort?.()}catch{}}requeueFromBatch(t,e){if(e.size===0)return;const i=t.filter(a=>e.has(a.entry_id)),n=new Set(i.map(a=>a.entry_id)),r=this.buffer.filter(a=>!n.has(a.entry_id));this.buffer.splice(0,this.buffer.length,...i,...r)}executePlan(t,e,i){const n=new Set,r=this.visibleRoute(e.visibleEntries);if(r==="critical"){if(this.abortCritical(),!this.canMutate())return{inactive:!0,requeueEntryIds:n};for(const o of e.visibleEntries)n.add(o.entry_id);for(const o of e.hiddenEntries)n.add(o.entry_id);return{inactive:!1,requeueEntryIds:n}}if(this.runNode&&r==="none")return{inactive:!1,requeueEntryIds:new Set([...e.hiddenEntries,...e.visibleEntries].map(o=>o.entry_id))};const a=e.visibleEntries.length>0?this.digest(e.visibleEntries,i):[],[d,...f]=a;for(const o of f)for(const c of o.entries)n.add(c.entry_id);if(e.hiddenEntries.length>0){const o=this.contextCards(t,e.hiddenEntries),c=this.sendContext(t,e.hiddenEntries,o,r,d===void 0,i);if(c==="inactive")return{inactive:!0,requeueEntryIds:n};if(c==="failed")for(const u of e.hiddenEntries)n.add(u.entry_id)}if(!this.canMutate())return{inactive:!0,requeueEntryIds:n};if(d!==void 0){const o=this.sendVisible(d.entries,d.cards,d.text,re(d),r,i);if(o==="inactive")return{inactive:!0,requeueEntryIds:n};if(o==="failed")for(const c of d.entries)n.add(c.entry_id);else d.kind==="human"&&(L(t,d.text),V(t,d.text))}return{inactive:!1,requeueEntryIds:n}}flushOrdinary(t){if(this.buffer.length===0)return"empty";const e=this.ordinaryPlan();if(e.deferredHold)return"held";if(this.pendingHandoffs.length+e.sendCount>v)return"capacity-blocked";const i=[...this.buffer],n=this.executePlan(t,e,"poll");return n.inactive||(this.buffer.splice(0,i.length),this.requeueFromBatch(i,n.requeueEntryIds)),"attempted"}async prependHeldDeferredInbox(t){if(!this.canMutate()||this.nodeId===void 0||P())return;const e=this.ordinaryPlan();if(!e.deferredHold)return;const i=e.visibleEntries.length===0?[]:this.digest(e.visibleEntries,"poll"),n=+(e.hiddenEntries.length>0)+i.length;if(this.pendingHandoffs.length+n>v)return;const r=[...this.buffer];this.promptJoinInFlight=!0;try{this.runNode&&this.pi.appendEntry("crtr-turn-input",{message_ids:[...e.hiddenEntries,...e.visibleEntries].map(a=>a.entry_id)}),e.hiddenEntries.length>0&&await this.sendPromptJoinDelivery(t,"hidden",e.hiddenEntries,this.contextCards(this.nodeId,e.hiddenEntries));for(const a of i)await this.sendPromptJoinDelivery(t,"visible",a.entries,[...a.cards,a.text]);if(!this.canMutate())return;this.buffer.splice(0,r.length)}finally{this.promptJoinInFlight=!1}}async sendPromptJoinDelivery(t,e,i,n){let r;try{r=F(i,e)}catch(f){this.raiseReadFatal("poll",f)}let a;try{await p.fresh(async f=>{a=f,w({level:"info",event:"inbox.delivery.started",operation_id:f,fields:y(r)});for(const o of n)await t.sendCustomMessage({customType:_,content:o,display:!0})})}catch(f){throw a===void 0&&this.raiseReadFatal("poll",f),M(a,r,"send",f),f}a===void 0&&this.raiseReadFatal("poll",new Error(`${e} prompt-join delivery returned without an operation id`));const d={operationId:a,...r,settleAtAgentSettled:!0};if(!this.canMutate()){this.disposed&&this.disposalReason!==void 0&&k(d,this.disposalReason);return}this.pendingHandoffs.push(d)}coveredEntryIds(t){const e=new Set;for(const i of this.pendingHandoffs)if(i.channel===t)for(const n of i.entryIds)e.add(n);return e}retryPendingCommit(t){const e=this.pendingCommit;if(e===void 0)return Promise.resolve("settled");if(e.attempt!==void 0)return e.attempt;const i=this.attemptPendingCommit(t,e).finally(()=>{e.attempt===i&&(e.attempt=void 0)});return e.attempt=i,i}async attemptPendingCommit(t,e){let i=!1;try{const r=await $(t,e.receipts);if(r.action==="hold")return"refresh_held";for(const a of e.receipts){const d=r.results.find(f=>f.delivery_id===a.delivery_id);if(d?.outcome!==a.disposition&&d?.outcome!=="stale")throw new Error("daemon returned no terminal mail settlement outcome")}i=r.results.every(a=>a.outcome==="acknowledged")}catch(r){if(this.pendingCommit===e)for(const a of e.handoffs)M(a.operationId,a,"receipt_commit",r);return"held"}if(this.pendingCommit!==e)return"settled";for(const r of e.entryIds)this.claims.delete(r);if(e.receipts.some(r=>r.disposition==="released")){const r=new Set(e.entryIds);this.buffer.splice(0,this.buffer.length,...this.buffer.filter(a=>!r.has(a.entry_id)))}this.pendingCommit=void 0;const n=this.detachPending(r=>r.entryIds.every(a=>!this.claims.has(a)));for(const r of n)i&&se(r);return"settled"}async settle(t,e,i,n=!1){if(i)try{if(e?.hasPendingMessages?.()===!0)return"held"}catch{}if(this.pendingCommit!==void 0)return this.retryPendingCommit(t);const r=X(),a=!r&&this.pendingHandoffs.some(h=>h.awaitingDequeue!==void 0)&&await this.nodeRefreshing(t);if(this.pendingCommit!==void 0)return this.retryPendingCommit(t);const d=new Set(this.buffer.map(h=>h.entry_id)),f=new Set(a?this.pendingHandoffs.filter(h=>h.awaitingDequeue!==void 0).flatMap(h=>[...h.entryIds]):[]),o=this.pendingHandoffs.filter(h=>(n||h.settleAtAgentSettled!==!0)&&h.entryIds.every(g=>!f.has(g))),c=new Set(o.flatMap(h=>[...h.entryIds])),u=[...this.claims.keys()].filter(h=>r||c.has(h)&&!d.has(h));return u.length===0?"settled":(this.pendingCommit={handoffs:o,entryIds:u,receipts:u.map(h=>{const g=this.claims.get(h);return{delivery_id:g.delivery_id,attempts:g.attempts,disposition:r?"released":"acknowledged"}})},this.retryPendingCommit(t))}async nodeRefreshing(t){try{return(await G(t)).node.intent==="refresh"}catch{return!0}}detachPending(t){const e=[];for(let i=this.pendingHandoffs.length-1;i>=0;i-=1){const n=this.pendingHandoffs[i];t(n)&&e.push(...this.pendingHandoffs.splice(i,1))}return e.reverse(),e}}function le(s,t){m?.dispose("reload",!1);const e=new fe(s,t,++ie);m=e;const i=l(n=>e.prependHeldDeferredInbox(n),"promptJoin");globalThis[te]=i;try{e.start()}catch(n){throw e.dispose("reload",!1),n}return e}l(le,"installWatcher");function he(s){const t=le(s,ne());return()=>t.dispose("shutdown",!1)}l(he,"registerCanvasInboxWatcher");var Fe=he;export{Fe as default,he as registerCanvasInboxWatcher};

package/dist/pi-extensions/canvas-passive-context.js

@@ -2,7 +2,7 @@ var v=Object.defineProperty;var l=(t,e)=>v(t,"name",{value:e,configurable:!0});i
 `))return t;const e=t.indexOf(`
 ---
 `,4);return e===-1?t:t.slice(e+5)}l(P,"stripFrontmatter");async function j(t,e){if(e.ref!==void 0&&e.ref!==""){const n=e.data?.report_body;if(typeof n=="string"&&n.trim()!==""){const i=n.trim();return i.length>y?`${i.slice(0,y)}
-\u2026 (truncated; read the full report with \`crtr canvas history read ${e.ref}\`)`:i}if(h(e.ref))try{const{content:i}=await w(t,e.ref),f=P(i).trim();if(f!=="")return f.length>y?`${f.slice(0,y)}
+\u2026 (truncated; read the full report with \`crtr canvas read ${e.ref}\`)`:i}if(h(e.ref))try{const{content:i}=await w(t,e.ref),f=P(i).trim();if(f!=="")return f.length>y?`${f.slice(0,y)}
 \u2026 (truncated; full report at ${e.ref})`:f}catch(i){if(!(i instanceof b)||i.status!==404)throw i}}const r=e.data?.body;return typeof r=="string"&&r.trim()!==""?r.trim():e.label}l(j,"entryContent");function m(t){return t.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;")}l(m,"attr");async function B(t,e=p()??""){const r=(await Promise.all(t.map(async n=>{const i=m(n.from??"system"),f=n.from_name!==void 0&&n.from_name!==""?` from_name="${m(n.from_name)}"`:"",o=n.ref!==void 0&&n.ref!==""?` ref="${m(n.ref)}"`:"";return`<update from="${i}"${f} kind="${m(n.kind)}" at="${m(n.ts)}"${o}>
 ${await j(e,n)}
 </update>`}))).join(`

package/dist/pi-extensions/canvas-recap.js

@@ -7,5 +7,5 @@ var W=Object.defineProperty;var a=(n,s)=>W(n,"name",{value:s,configurable:!0});i
 
 `):Array.from({length:o},(l,m)=>{const f=Math.round(m*(t.length-1)/(o-1));return t[f]}).join(`
 
-`)}a(ee,"buildNamingConversation");function te(n,s=U,r){const t=B();if(t===void 0||t.trim()==="")return;let o,u,l,m;const f=a(i=>{const e=i.model?.provider?.trim(),c=i.model?.id?.trim();e&&c&&(m=`${e}/${c}`)},"captureLiveModel");let p=Date.now(),d=0,g,_=!1,S=!1,E=!1,h=!1;const v=a(()=>o!==void 0&&typeof o.setWidget=="function","canPaint"),A=a(i=>{try{o?.notify?.(i,"info")}catch{}},"notify"),P=a(()=>{if(v())try{o.setWidget($,void 0,{placement:"aboveEditor"})}catch{}},"clearRecap"),D=a(i=>{if(!v()||i==="")return;const e=i.split(`
-`).filter(c=>c.trim()!=="");if(e.length!==0)try{o.setWidget($,e,{placement:"aboveEditor"})}catch{}},"showRecap"),I=a(()=>{p=Date.now(),d+=1,E=!1,_&&(S=!0)},"onMessage"),j=a(i=>{if(!(n.getSessionName===void 0||n.setSessionName===void 0)){if(r!==void 0){const e=n.getSessionName();if(e===void 0)return;r(t,i,()=>n.getSessionName?.()===e,c=>{try{n.setSessionName?.(c)}catch{}});return}G(t).then(({node:e})=>{if(e.name.trim()!==""&&e.name!==e.kind)return;const c=F(e);n.getSessionName?.()===c&&H(t,i,{name:e.name,description:e.description??"",title:e.title??"",icon:e.icon??"",kind:e.kind},()=>n.getSessionName?.()===c,R=>{try{n.setSessionName?.(R)}catch{}})}).catch(()=>{})}},"refreshAutomaticName"),x=a(i=>{if(!v()||u===void 0||h)return;const e=g,c=l?.review_binding?.review_id??u.getEntries().map(y=>y.details?.reviewId).find(y=>typeof y=="string"),R=Z(u,e,c);if(R===""){E=!0,_=!1,S=!1,P();return}E=!1;const T=i?ee(u,e,c):"",w=d;h=!0,i&&(A("Generating recap\u2026"),j(T));let k;try{k=K(t)??void 0}catch{}s(R,y=>{!i&&d!==w||!v()||V(t,y).then(()=>{!i&&d!==w||!v()||(_=!0,S=d!==w,D(y),i&&A("Recap ready"))}).catch(L=>A(`Recap could not be saved: ${String(L)}`)).finally(()=>{h=!1})},m,k),setTimeout(()=>{h=!1},3e4).unref?.()},"requestRecap");n.registerCommand?.("recap",{description:"Generate a Goal/State recap and refresh the original generated session title",handler:a((i,e)=>{o=e.ui,u=e.sessionManager,f(e),x(!0)},"handler")}),n.on("session_start",(i,e)=>{o=e.ui,u=e.sessionManager,f(e),l=void 0,G(t).then(c=>{l=c.node}).catch(()=>{}),p=Date.now(),d=0,g=void 0,_=!1,S=!1,E=!1,h=!1,P()}),n.on("input",(i,e)=>{I()}),n.on("message_update",(i,e)=>{const c=i?.message;c?.role==="assistant"&&(g=c),I()}),n.on("turn_end",(i,e)=>{g=void 0,f(e),I()}),M!==void 0&&clearInterval(M);const N=setInterval(()=>{try{if(!v()||u===void 0||E||_&&!S||h||Date.now()-p<Y())return;x(!1)}catch{}},z);typeof N.unref=="function"&&N.unref(),M=N,n.on("session_shutdown",()=>{clearInterval(N),M===N&&(M=void 0)})}a(te,"registerCanvasRecap");var de=te;export{de as default,te as registerCanvasRecap};
+`)}a(ee,"buildNamingConversation");function te(n,s=U,r){const t=B();if(t===void 0||t.trim()==="")return;let o,u,l,m;const f=a(i=>{const e=i.model?.provider?.trim(),c=i.model?.id?.trim();e&&c&&(m=`${e}/${c}`)},"captureLiveModel");let p=Date.now(),d=0,g,y=!1,_=!1,S=!1,h=!1;const v=a(()=>o!==void 0&&typeof o.setWidget=="function","canPaint"),A=a(i=>{try{o?.notify?.(i,"info")}catch{}},"notify"),P=a(()=>{if(v())try{o.setWidget($,void 0,{placement:"aboveEditor"})}catch{}},"clearRecap"),D=a(i=>{if(!v()||i==="")return;const e=i.split(`
+`).filter(c=>c.trim()!=="");if(e.length!==0)try{o.setWidget($,e,{placement:"aboveEditor"})}catch{}},"showRecap"),I=a(()=>{p=Date.now(),d+=1,S=!1,y&&(_=!0)},"onMessage"),j=a(i=>{if(!(n.getSessionName===void 0||n.setSessionName===void 0)){if(r!==void 0){const e=n.getSessionName();if(e===void 0)return;r(t,i,()=>n.getSessionName?.()===e,c=>{try{n.setSessionName?.(c)}catch{}});return}G(t).then(({node:e})=>{if(e.name.trim()!==""&&e.name!==e.kind)return;const c=F(e);n.getSessionName?.()===c&&H(t,i,{name:e.name,description:e.description??"",title:e.title??"",icon:e.icon??"",kind:e.kind},()=>n.getSessionName?.()===c,R=>{try{n.setSessionName?.(R)}catch{}})}).catch(()=>{})}},"refreshAutomaticName"),x=a(i=>{if(!v()||u===void 0||h)return;const e=g,c=l?.review_binding?.review_id??u.getEntries().map(N=>N.details?.reviewId).find(N=>typeof N=="string"),R=Z(u,e,c);if(R===""){S=!0,y=!1,_=!1,P();return}S=!1;const T=i?ee(u,e,c):"",w=d;h=!0,i&&(A("Generating recap\u2026"),j(T)),K(t).catch(()=>null).then(N=>s(R,k=>{!i&&d!==w||!v()||V(t,k).then(()=>{!i&&d!==w||!v()||(y=!0,_=d!==w,D(k),i&&A("Recap ready"))}).catch(L=>A(`Recap could not be saved: ${String(L)}`)).finally(()=>{h=!1})},m,N??void 0)),setTimeout(()=>{h=!1},3e4).unref?.()},"requestRecap");n.registerCommand?.("recap",{description:"Generate a Goal/State recap and refresh the original generated session title",handler:a((i,e)=>{o=e.ui,u=e.sessionManager,f(e),x(!0)},"handler")}),n.on("session_start",(i,e)=>{o=e.ui,u=e.sessionManager,f(e),l=void 0,G(t).then(c=>{l=c.node}).catch(()=>{}),p=Date.now(),d=0,g=void 0,y=!1,_=!1,S=!1,h=!1,P()}),n.on("input",(i,e)=>{I()}),n.on("message_update",(i,e)=>{const c=i?.message;c?.role==="assistant"&&(g=c),I()}),n.on("turn_end",(i,e)=>{g=void 0,f(e),I()}),M!==void 0&&clearInterval(M);const E=setInterval(()=>{try{if(!v()||u===void 0||S||y&&!_||h||Date.now()-p<Y())return;x(!1)}catch{}},z);typeof E.unref=="function"&&E.unref(),M=E,n.on("session_shutdown",()=>{clearInterval(E),M===E&&(M=void 0)})}a(te,"registerCanvasRecap");var de=te;export{de as default,te as registerCanvasRecap};

package/dist/pi-extensions/canvas-stophook.d.ts

@@ -26,7 +26,7 @@ interface PiLike {
  *  node's primary job — so no persona is ever steered at a bare `node promote` (which framed promotion as a heavy
  *  "become an orchestrator" step and bred yield-avoidance).
  *
- *  - orchestrator (terminal OR resident): checkpoint context/roadmap.md, then
+ *  - orchestrator (terminal OR resident): bring the roadmap current, then
  *    yield (it already has a roadmap to bring current first).
  *  - resident/base (root conversation): yield to continue fresh if the chat is
  *    growing into a job, else wrap up — a root can simply end.

package/dist/pi-extensions/canvas-stophook.js

@@ -1 +1 @@
-var N=Object.defineProperty;var c=(n,t)=>N(n,"name",{value:t,configurable:!0});import{envNodeId as U}from"../shared/env.js";import{stripCdPrefix as q}from"../shared/strip-cd-prefix.js";import{contextDir as J}from"../core/canvas/paths.js";import{mutateBrokerFault as T,recordBrokerTelemetry as H,recordBrokerTurn as b,putBrokerTelemetry as W,clearBrokerPushedFinal as j,consumeBrokerPushedFinal as Y}from"../core/runtime/broker/daemon-ops.js";import{bindBrokerSession as z,brokerExtensionState as $,relaunchBrokerRoot as G,settleBroker as M}from"../core/runtime/broker/daemon-ops.js";import{emitEvent as C}from"../core/events/emit.js";import{activeBackgroundBashJobs as L}from"../core/bash-jobs.js";import{CONTEXT_NUDGE_CUSTOM_TYPE as V,formatCard as X}from"../shared/generated-context.js";import{isReviewBoundary as K}from"../core/runtime/session-visibility.js";import{clearRefusedTurn as Q,isRuntimeTeardownInProgress as Z,refuseTurn as ee,runRefreshAbort as te}from"../core/runtime/broker/extension-abort.js";import{announceMessageOrigin as P}from"../core/runtime/stamp/channel.js";const F=80;function ne(n,t){const a=t??{},s=c(m=>typeof m=="string"?m:"","pick"),g=q(s(a.command).trim())||s(a.path)||s(a.file_path)||s(a.pattern)||s(a.description)||s(a.prompt),y=(g!==""?`${n}: ${g}`:n).replace(/\s+/g," ").trim();return y.length>F?y.slice(0,F):y}c(ne,"summarizeActivity");function oe(n){for(let t=n.length-1;t>=0;t--)if(n[t]?.role==="assistant")return n[t]}c(oe,"lastAssistantMessage");function re(n){try{const t=n?.sessionManager?.getBranch();if(!Array.isArray(t))return[];const a=new Set;for(const s of t){if(!K(s))continue;const d=s.details?.reviewId;typeof d=="string"&&a.add(d)}return[...a]}catch{return[]}}c(re,"currentReviewBoundaryIds");const O=1e4,v=[13e4,15e4,17e4,185e3,2e5];function se(n){const t=v[0],a=v[v.length-1];if(n<t)return null;if(n>=a)return a+Math.floor((n-a)/O)*O;let s=t;for(const d of v)n>=d&&(s=d);return s}c(se,"steerBand");function ae(n,t,a){const s=Math.round(n/1e3),d=n>=185e3;if(a==="orchestrator")return n<15e4?`Context ~${s}k and growing. When you reach a good stopping point, consider updating context/roadmap.md and running \`crtr node yield\` to refresh against it \u2014 no rush yet.`:d?`Context ~${s}k \u2014 this is getting long. Stop taking on new work now: checkpoint context/roadmap.md, hand off anything outstanding, and \`crtr node yield\` immediately to refresh before this context overflows.`:`Context ~${s}k. Update context/roadmap.md so a fresh revive can continue, delegate any outstanding work, then \`crtr node yield\` to refresh.`;if(t==="resident"){const g="If substantial work remains, `crtr node yield` to continue fresh against your goal and your note. Add --promote only when worthwhile independent work can run in parallel and coordinating it should become your primary job; `crtr node yield -h` has the boundary.";return n<15e4?`Context ~${s}k and growing. ${g} Otherwise no rush \u2014 wrap up when you reach a good stopping point.`:d?`Context ~${s}k \u2014 this is getting long. Wrap up now before this context overflows: finish what's in hand, or \`crtr node yield\` immediately to continue fresh against your goal and your note if substantial work remains.`:`Context ~${s}k. ${g} If you're near done, just finish here; if there's more open-ended work, \`crtr node yield\` rather than letting this context grow.`}return n<15e4?`Context ~${s}k and growing. If you're near done, finish with \`crtr push final\`. If real work remains, \`crtr node yield\` to continue in a fresh window against your goal and your note \u2014 no rush yet.`:d?`Context ~${s}k \u2014 this is getting long. Wrap up now before this context overflows: \`crtr push final\` if you're close, otherwise \`crtr node yield\` immediately to continue in a fresh window against your goal and your note.`:`Context ~${s}k. If you're close, finish with \`crtr push final\`; otherwise \`crtr node yield\` now to refresh into a clean window and keep going against your goal and your note.`}c(ae,"steerNote");function ie(n){const t=U();if(t===void 0||t.trim()==="")return;let a=0,s=0,d="",g=null,y=null;const m=new Set,S=c(()=>L(J(t)).length>0,"backgroundJobsRunning"),l=c((e,r)=>{C({event:"broker.daemon.operation.failed",level:"error",node_id:t,error:r,fields:{operation:e}})},"emitDaemonOperationFailure"),B=c((e,r)=>{if(e.action==="reprompt"){P(e.prompt,{type:"runtime",kind:"stop-guard"}),n.sendUserMessage(e.prompt,{deliverAs:"followUp"});return}if(e.action==="shutdown")try{r?.shutdown?.()}catch{}},"enactSettleDirective"),D=3e3;let I=0,k=Promise.resolve();const R=c((e,r)=>{const o=new Date().toISOString(),f={tokens_in:a,tokens_out:s,model:d,context_tokens:e,last_activity:r,updated_at:o};k=k.then(()=>W(t,f)).catch(u=>l("telemetry-record",u));const h={tokens_in:a,context_tokens:e,last_activity:r,updated_at:o};k=k.then(()=>H(t,h)).catch(u=>l("telemetry",u))},"publishTelemetry"),_=c(()=>{const e=Date.now();e-I<D||(I=e,Promise.all([b(t,{event:"progress"}),T(t,{op:"clear",link:"daemon\u2192node"})]).catch(r=>l("turn_progress",r)))},"heartbeat");n.on("session_start",async(e,r)=>{try{const o=r?.sessionManager?.getSessionId?.();if(typeof o!="string"||o==="")return;const f=r?.sessionManager?.getSessionFile?.(),h=typeof f=="string"&&f!==""?f:null,u=typeof e?.reason=="string"?e.reason:null;u==="new"&&(a=0,s=0,m.clear());const i=await z(t,{piSessionId:o,sessionFile:h,pid:process.pid,reason:u,reviewBoundaryIds:re(r)});if(i.action==="shutdown"){try{r?.shutdown?.()}catch{}return}if(i.action==="relaunch_root"){G(t).catch(p=>{const w=p instanceof Error?p.message:String(p);r?.ui?.notify?.(`/new refused: ${w}`,"error"),C({event:"broker.daemon.operation.failed",level:"error",node_id:t,error:p,fields:{operation:"relaunch_root"}})});return}}catch(o){C({event:"broker.daemon.operation.failed",level:"error",node_id:t,error:o,fields:{operation:"session_bound"}})}}),n.on("agent_start",async(e,r)=>{try{if(!(await b(t,{event:"started"})).applied)throw new Error("daemon refused turn open")}catch(o){l("turn_open",o),r?.ui?.notify?.("Turn refused: the broker no longer owns this node.","error"),ee(()=>r?.abort?.())}}),n.on("input",async()=>{Q();try{await j(t)}catch(e){throw l("clear_pushed_final",e),e}}),n.on("tool_execution_start",e=>{try{y=ne(String(e?.toolName??""),e?.args),R(g,y),_()}catch{}}),n.on("tool_execution_update",()=>{try{_()}catch{}}),n.on("message_update",()=>{try{_()}catch{}}),n.on("tool_execution_end",async(e,r)=>{try{if(_(),(await $(t)).node.intent==="refresh")try{te(()=>r?.abort?.())}catch{}}catch{}}),n.on("session_shutdown",async(e,r)=>{try{await b(t,{event:"closed",end_reason:"teardown-aborted"})}catch(o){l("turn_close_teardown",o)}if(e?.reason==="quit")try{const o=await M(t,{stopReason:"quit",backgroundJobsRunning:S(),pushedFinal:!1});B(o,r)}catch(o){l("settle_quit",o)}});const E=c(e=>{e?.role!=="assistant"||e.usage==null||(a+=Number(e.usage.input??0)||0,s+=Number(e.usage.output??0)||0,typeof e.model=="string"&&e.model!==""&&(d=e.model))},"accumulate");n.on("turn_end",async(e,r)=>{E(e?.message);let o=null;try{const i=r.getContextUsage()?.tokens;typeof i=="number"&&(o=i)}catch{}o!==null&&(g=o),R(o,y),_();try{await Promise.all([T(t,{op:"clear",link:"daemon\u2192node"}),T(t,{op:"clear",link:"pi\u2192provider"})])}catch(i){l("turn_end_fault_clear",i)}const f=Array.isArray(e?.message?.content)?e.message.content:[],h=e?.message?.stopReason??"",u=h!=="error"&&h!=="aborted"&&f.some(i=>i?.type==="toolCall");try{const p=(await $(t)).node,w=o!==null?se(o):null;if(w!==null&&!m.has(w)){m.add(w);const A=X("context-nudge",{},ae(w,p.lifecycle,p.mode));u?(P(A,{type:"runtime",kind:"context-nudge"}),n.sendUserMessage(A,{deliverAs:"steer"})):n.sendMessage({customType:V,content:A,display:!0},{deliverAs:"nextTurn"})}}catch(i){l("turn_boundary",i)}});let x=null;n.on("agent_end",e=>{x=e;try{const r=Array.isArray(e?.messages)?e.messages:[];for(const o of r)E(o)}catch{}}),n.on("agent_settled",async(e,r)=>{const o=x;if(x=null,Z())return;try{await b(t,{event:"closed",end_reason:"settled"})}catch(i){l("turn_close",i);return}const f=Array.isArray(o?.messages)?o.messages:[],h=oe(f),u=typeof h?.stopReason=="string"?h.stopReason:"";try{const i=o===null?{pushedFinal:!1}:await Y(t),p=await M(t,{stopReason:u,backgroundJobsRunning:S(),pushedFinal:i.pushedFinal});B(p,r)}catch(i){l("settle",i)}})}c(ie,"registerCanvasStophook");var ke=ie;export{ke as default,ie as registerCanvasStophook,ae as steerNote};
+var N=Object.defineProperty;var c=(n,t)=>N(n,"name",{value:t,configurable:!0});import{envNodeId as U}from"../shared/env.js";import{stripCdPrefix as q}from"../shared/strip-cd-prefix.js";import{contextDir as J}from"../core/canvas/paths.js";import{mutateBrokerFault as T,recordBrokerTelemetry as H,recordBrokerTurn as b,putBrokerTelemetry as W,clearBrokerPushedFinal as j,consumeBrokerPushedFinal as Y}from"../core/runtime/broker/daemon-ops.js";import{bindBrokerSession as z,brokerExtensionState as $,relaunchBrokerRoot as G,settleBroker as M}from"../core/runtime/broker/daemon-ops.js";import{emitEvent as C}from"../core/events/emit.js";import{activeBackgroundBashJobs as L}from"../core/bash-jobs.js";import{CONTEXT_NUDGE_CUSTOM_TYPE as V,formatCard as X}from"../shared/generated-context.js";import{isReviewBoundary as K}from"../core/runtime/session-visibility.js";import{clearRefusedTurn as Q,isRuntimeTeardownInProgress as Z,refuseTurn as ee,runRefreshAbort as te}from"../core/runtime/broker/extension-abort.js";import{announceMessageOrigin as P}from"../core/runtime/stamp/channel.js";const F=80;function ne(n,t){const a=t??{},s=c(m=>typeof m=="string"?m:"","pick"),g=q(s(a.command).trim())||s(a.path)||s(a.file_path)||s(a.pattern)||s(a.description)||s(a.prompt),y=(g!==""?`${n}: ${g}`:n).replace(/\s+/g," ").trim();return y.length>F?y.slice(0,F):y}c(ne,"summarizeActivity");function re(n){for(let t=n.length-1;t>=0;t--)if(n[t]?.role==="assistant")return n[t]}c(re,"lastAssistantMessage");function oe(n){try{const t=n?.sessionManager?.getBranch();if(!Array.isArray(t))return[];const a=new Set;for(const s of t){if(!K(s))continue;const d=s.details?.reviewId;typeof d=="string"&&a.add(d)}return[...a]}catch{return[]}}c(oe,"currentReviewBoundaryIds");const O=1e4,v=[13e4,15e4,17e4,185e3,2e5];function se(n){const t=v[0],a=v[v.length-1];if(n<t)return null;if(n>=a)return a+Math.floor((n-a)/O)*O;let s=t;for(const d of v)n>=d&&(s=d);return s}c(se,"steerBand");function ae(n,t,a){const s=Math.round(n/1e3),d=n>=185e3;if(a==="orchestrator")return n<15e4?`Context ~${s}k and growing. When you reach a good stopping point, consider updating your roadmap (\`crtr doc edit roadmap\`) and running \`crtr node yield\` to refresh against it \u2014 no rush yet.`:d?`Context ~${s}k \u2014 this is getting long. Stop taking on new work now: bring your roadmap current, hand off anything outstanding, and \`crtr node yield\` immediately to refresh before this context overflows.`:`Context ~${s}k. Update your roadmap (\`crtr doc edit roadmap\`) so a fresh revive can continue, delegate any outstanding work, then \`crtr node yield\` to refresh.`;if(t==="resident"){const g="If substantial work remains, `crtr node yield` to continue fresh against your goal and your note. Add --promote only when worthwhile independent work can run in parallel and coordinating it should become your primary job; `crtr node yield -h` has the boundary.";return n<15e4?`Context ~${s}k and growing. ${g} Otherwise no rush \u2014 wrap up when you reach a good stopping point.`:d?`Context ~${s}k \u2014 this is getting long. Wrap up now before this context overflows: finish what's in hand, or \`crtr node yield\` immediately to continue fresh against your goal and your note if substantial work remains.`:`Context ~${s}k. ${g} If you're near done, just finish here; if there's more open-ended work, \`crtr node yield\` rather than letting this context grow.`}return n<15e4?`Context ~${s}k and growing. If you're near done, finish with \`crtr push final\`. If real work remains, \`crtr node yield\` to continue in a fresh window against your goal and your note \u2014 no rush yet.`:d?`Context ~${s}k \u2014 this is getting long. Wrap up now before this context overflows: \`crtr push final\` if you're close, otherwise \`crtr node yield\` immediately to continue in a fresh window against your goal and your note.`:`Context ~${s}k. If you're close, finish with \`crtr push final\`; otherwise \`crtr node yield\` now to refresh into a clean window and keep going against your goal and your note.`}c(ae,"steerNote");function ie(n){const t=U();if(t===void 0||t.trim()==="")return;let a=0,s=0,d="",g=null,y=null;const m=new Set,S=c(()=>L(J(t)).length>0,"backgroundJobsRunning"),u=c((e,o)=>{C({event:"broker.daemon.operation.failed",level:"error",node_id:t,error:o,fields:{operation:e}})},"emitDaemonOperationFailure"),B=c((e,o)=>{if(e.action==="reprompt"){P(e.prompt,{type:"runtime",kind:"stop-guard"}),n.sendUserMessage(e.prompt,{deliverAs:"followUp"});return}if(e.action==="shutdown")try{o?.shutdown?.()}catch{}},"enactSettleDirective"),D=3e3;let I=0,k=Promise.resolve();const R=c((e,o)=>{const r=new Date().toISOString(),f={tokens_in:a,tokens_out:s,model:d,context_tokens:e,last_activity:o,updated_at:r};k=k.then(()=>W(t,f)).catch(l=>u("telemetry-record",l));const h={tokens_in:a,context_tokens:e,last_activity:o,updated_at:r};k=k.then(()=>H(t,h)).catch(l=>u("telemetry",l))},"publishTelemetry"),_=c(()=>{const e=Date.now();e-I<D||(I=e,Promise.all([b(t,{event:"progress"}),T(t,{op:"clear",link:"daemon\u2192node"})]).catch(o=>u("turn_progress",o)))},"heartbeat");n.on("session_start",async(e,o)=>{try{const r=o?.sessionManager?.getSessionId?.();if(typeof r!="string"||r==="")return;const f=o?.sessionManager?.getSessionFile?.(),h=typeof f=="string"&&f!==""?f:null,l=typeof e?.reason=="string"?e.reason:null;l==="new"&&(a=0,s=0,m.clear());const i=await z(t,{piSessionId:r,sessionFile:h,pid:process.pid,reason:l,reviewBoundaryIds:oe(o)});if(i.action==="shutdown"){try{o?.shutdown?.()}catch{}return}if(i.action==="relaunch_root"){G(t).catch(p=>{const w=p instanceof Error?p.message:String(p);o?.ui?.notify?.(`/new refused: ${w}`,"error"),C({event:"broker.daemon.operation.failed",level:"error",node_id:t,error:p,fields:{operation:"relaunch_root"}})});return}}catch(r){C({event:"broker.daemon.operation.failed",level:"error",node_id:t,error:r,fields:{operation:"session_bound"}})}}),n.on("agent_start",async(e,o)=>{try{if(!(await b(t,{event:"started"})).applied)throw new Error("daemon refused turn open")}catch(r){u("turn_open",r),o?.ui?.notify?.("Turn refused: the broker no longer owns this node.","error"),ee(()=>o?.abort?.())}}),n.on("input",async()=>{Q();try{await j(t)}catch(e){throw u("clear_pushed_final",e),e}}),n.on("tool_execution_start",e=>{try{y=ne(String(e?.toolName??""),e?.args),R(g,y),_()}catch{}}),n.on("tool_execution_update",()=>{try{_()}catch{}}),n.on("message_update",()=>{try{_()}catch{}}),n.on("tool_execution_end",async(e,o)=>{try{if(_(),(await $(t)).node.intent==="refresh")try{te(()=>o?.abort?.())}catch{}}catch{}}),n.on("session_shutdown",async(e,o)=>{try{await b(t,{event:"closed",end_reason:"teardown-aborted"})}catch(r){u("turn_close_teardown",r)}if(e?.reason==="quit")try{const r=await M(t,{stopReason:"quit",backgroundJobsRunning:S(),pushedFinal:!1});B(r,o)}catch(r){u("settle_quit",r)}});const E=c(e=>{e?.role!=="assistant"||e.usage==null||(a+=Number(e.usage.input??0)||0,s+=Number(e.usage.output??0)||0,typeof e.model=="string"&&e.model!==""&&(d=e.model))},"accumulate");n.on("turn_end",async(e,o)=>{E(e?.message);let r=null;try{const i=o.getContextUsage()?.tokens;typeof i=="number"&&(r=i)}catch{}r!==null&&(g=r),R(r,y),_();try{await Promise.all([T(t,{op:"clear",link:"daemon\u2192node"}),T(t,{op:"clear",link:"pi\u2192provider"})])}catch(i){u("turn_end_fault_clear",i)}const f=Array.isArray(e?.message?.content)?e.message.content:[],h=e?.message?.stopReason??"",l=h!=="error"&&h!=="aborted"&&f.some(i=>i?.type==="toolCall");try{const p=(await $(t)).node,w=r!==null?se(r):null;if(w!==null&&!m.has(w)){m.add(w);const A=X("context-nudge",{},ae(w,p.lifecycle,p.mode));l?(P(A,{type:"runtime",kind:"context-nudge"}),n.sendUserMessage(A,{deliverAs:"steer"})):n.sendMessage({customType:V,content:A,display:!0},{deliverAs:"nextTurn"})}}catch(i){u("turn_boundary",i)}});let x=null;n.on("agent_end",e=>{x=e;try{const o=Array.isArray(e?.messages)?e.messages:[];for(const r of o)E(r)}catch{}}),n.on("agent_settled",async(e,o)=>{const r=x;if(x=null,Z())return;try{await b(t,{event:"closed",end_reason:"settled"})}catch(i){u("turn_close",i);return}const f=Array.isArray(r?.messages)?r.messages:[],h=re(f),l=typeof h?.stopReason=="string"?h.stopReason:"";try{const i=r===null?{pushedFinal:!1}:await Y(t),p=await M(t,{stopReason:l,backgroundJobsRunning:S(),pushedFinal:i.pushedFinal});B(p,o)}catch(i){u("settle",i)}})}c(ie,"registerCanvasStophook");var ke=ie;export{ke as default,ie as registerCanvasStophook,ae as steerNote};

package/dist/prompts/review.js

@@ -32,9 +32,9 @@ seams to fall between \u2014 skip it for self-contained specs.
 
 For larger specs touching established patterns, optionally spawn a Task
 agent (\`general-purpose\`, \`sonnet\`) to cross-check the spec's design
-against the applicable project memory documents (discover them with
-\`crtr memory list\` and load them with \`crtr memory read\`) and the files they
-reference, looking for contradictions with project conventions. Skip for small
+against the repo's documents (discover them with \`crtr canvas list --type document\`
+or \`crtr canvas search\` and load them with \`crtr canvas read\`) and the files
+they reference, looking for contradictions with project conventions. Skip for small
 specs.
 
 ## Calibration

package/dist/shared/env.d.ts

@@ -4,6 +4,11 @@ export declare function envNodeId(): string | undefined;
 export declare function isSandboxedNode(): boolean;
 /** The app that owns the current node, supplied in its broker launch identity. */
 export declare function envGrantee(): string | undefined;
+/** Set to '1' by `nodeEnv` for an app-started run's brokers, which admit inbox
+ *  mail only between agent runs. Terminal nodes also carry `CRTR_RUN_ID`, so
+ *  that variable is not this signal. */
+export declare const INBOX_BETWEEN_TURNS_ENV = "CRTR_INBOX_BETWEEN_TURNS";
+export declare function envInboxBetweenTurns(): boolean;
 /** The current run's scope allow-list; null means the row inherits everything. */
 export declare function envScopes(): readonly string[] | null;
 /** Whether a launched scope list covers a capability. Null means not narrowed. */

package/dist/shared/env.js

@@ -1 +1 @@
-var _=Object.defineProperty;var e=(n,r)=>_(n,"name",{value:r,configurable:!0});import{covers as R}from"@north-light/crouter-identity";function c(){return process.env.CRTR_NODE_ID}e(c,"envNodeId");function x(){return process.platform==="linux"&&!!(c()&&process.env.CRTR_API_SOCKET)}e(x,"isSandboxedNode");function S(){return process.env.CRTR_GRANTEE}e(S,"envGrantee");function N(){const n=process.env.CRTR_SCOPES;return n===void 0?null:n===""?[]:n.split(",")}e(N,"envScopes");function a(n,r){return n==null?!0:n.some(o=>R(o,r))}e(a,"scopeAllowed");function O(){return process.env.CRTR_EXECUTION_ID}e(O,"envExecutionId");function I(){return process.env.CRTR_PROFILE_ID}e(I,"envProfileId");function L(){return process.env.CRTR_NODE_CWD}e(L,"envNodeCwd");function P(){return process.env.CRTR_MODEL_INTENT}e(P,"envModelIntent");function B(){return process.env.CRTR_MODEL_EXACT==="1"}e(B,"envModelExact");function U(){return process.env.CRTR_HOME}e(U,"envHomeOverride");function m(){return process.env.CRTR_RUNTIME_HOME}e(m,"envRuntimeHomeOverride");function t(n,r){if(n===void 0)return r;const o=Number(n);return Number.isFinite(o)&&o>0?o:r}e(t,"parsePositiveMs");const i=5*6e4;function l(){return t(process.env.CRTR_STREAM_WATCHDOG_MS,i)}e(l,"envStreamWatchdogMs");const p=800;function H(){return t(process.env.CRTR_WATCHER_TICK_MS,p)}e(H,"envWatcherTickMs");const T=1e3;function G(){return t(process.env.CRTR_WATCHER_DEBOUNCE_MS,T)}e(G,"envWatcherDebounceMs");const v=6e4;function F(){return t(process.env.CRTR_RECAP_IDLE_MS,v)}e(F,"envRecapIdleMs");function K(){const n=process.env.CRTR_RECAP_MODEL;return n!==void 0&&n.trim()!==""?n.trim():void 0}e(K,"envRecapModelOverride");const E=300*1e3;function W(){return t(process.env.CRTR_BASH_VALVE_MS,E)}e(W,"envBashValveMs");const d=60*1e3;function k(){return t(process.env.CRTR_BASH_AUTO_BG_DEADLINE_MS,d)}e(k,"envBashAutoBgDeadlineMs");function b(){const n=process.env.CRTR_PIDFILE;return n!==void 0&&n!==""?n:void 0}e(b,"envPidfileOverride");const f="@earendil-works/pi-coding-agent";function g(){return process.env.CRTR_BROKER_ENGINE??f}e(g,"envBrokerEngine");function V(){return process.env.CRTR_PI_BINARY}e(V,"envPiBinaryOverride");function h(){return process.env.CRTR_NO_DAEMON_AUTOSTART==="1"}e(h,"envNoDaemonAutostart");function X(){return process.env.CRTRD_TCP}e(X,"envCrtrdTcp");function w(){const n=process.env.CRTRD_TOKEN;return n!==void 0&&n!==""?n:void 0}e(w,"envCrtrdToken");function y(){return process.env.CRTR_NO_EXPORTS==="1"}e(y,"envNoExports");function Y(){return process.env.CRTR_DEBUG==="1"}e(Y,"envDebug");function u(n){if(n===void 0||n==="")return;const r=Number(n);return Number.isSafeInteger(r)&&r>=1?r:void 0}e(u,"parsePositiveInteger");function j(){return u(process.env.CRTR_MAX_LIVE_BROKERS)}e(j,"envMaxLiveBrokers");function q(){return u(process.env.CRTR_WARN_LIVE_BROKERS)}e(q,"envWarnLiveBrokers");function s(n){if(n===void 0)return;const r=Number(n);return Number.isFinite(r)&&r>0?r:void 0}e(s,"parsePositiveMsNoDefault");function z(){return s(process.env.CRTR_TEST_UNATTENDED_PARK_MS)}e(z,"envTestUnattendedParkMs");function J(){return s(process.env.CRTR_UNATTENDED_PARK_MS)}e(J,"envUnattendedParkMs");function C(){return s(process.env.CRTR_TEST_PARK_SUMMARY_GRACE_MS)}e(C,"envTestParkSummaryGraceMs");const A=5*6e4;function Q(){return C()??A}e(Q,"parkSummaryGraceMs");export{k as envBashAutoBgDeadlineMs,W as envBashValveMs,g as envBrokerEngine,X as envCrtrdTcp,w as envCrtrdToken,Y as envDebug,O as envExecutionId,S as envGrantee,U as envHomeOverride,j as envMaxLiveBrokers,B as envModelExact,P as envModelIntent,h as envNoDaemonAutostart,y as envNoExports,L as envNodeCwd,c as envNodeId,V as envPiBinaryOverride,b as envPidfileOverride,I as envProfileId,F as envRecapIdleMs,K as envRecapModelOverride,m as envRuntimeHomeOverride,N as envScopes,l as envStreamWatchdogMs,C as envTestParkSummaryGraceMs,z as envTestUnattendedParkMs,J as envUnattendedParkMs,q as envWarnLiveBrokers,G as envWatcherDebounceMs,H as envWatcherTickMs,x as isSandboxedNode,Q as parkSummaryGraceMs,a as scopeAllowed};
+var _=Object.defineProperty;var e=(n,r)=>_(n,"name",{value:r,configurable:!0});import{covers as R}from"@north-light/crouter-identity";function c(){return process.env.CRTR_NODE_ID}e(c,"envNodeId");function D(){return process.platform==="linux"&&!!(c()&&process.env.CRTR_API_SOCKET)}e(D,"isSandboxedNode");function S(){return process.env.CRTR_GRANTEE}e(S,"envGrantee");const i="CRTR_INBOX_BETWEEN_TURNS";function a(){return process.env[i]==="1"}e(a,"envInboxBetweenTurns");function O(){const n=process.env.CRTR_SCOPES;return n===void 0?null:n===""?[]:n.split(",")}e(O,"envScopes");function I(n,r){return n==null?!0:n.some(o=>R(o,r))}e(I,"scopeAllowed");function B(){return process.env.CRTR_EXECUTION_ID}e(B,"envExecutionId");function U(){return process.env.CRTR_PROFILE_ID}e(U,"envProfileId");function L(){return process.env.CRTR_NODE_CWD}e(L,"envNodeCwd");function P(){return process.env.CRTR_MODEL_INTENT}e(P,"envModelIntent");function m(){return process.env.CRTR_MODEL_EXACT==="1"}e(m,"envModelExact");function l(){return process.env.CRTR_HOME}e(l,"envHomeOverride");function H(){return process.env.CRTR_RUNTIME_HOME}e(H,"envRuntimeHomeOverride");function t(n,r){if(n===void 0)return r;const o=Number(n);return Number.isFinite(o)&&o>0?o:r}e(t,"parsePositiveMs");const T=5*6e4;function W(){return t(process.env.CRTR_STREAM_WATCHDOG_MS,T)}e(W,"envStreamWatchdogMs");const p=800;function G(){return t(process.env.CRTR_WATCHER_TICK_MS,p)}e(G,"envWatcherTickMs");const E=1e3;function F(){return t(process.env.CRTR_WATCHER_DEBOUNCE_MS,E)}e(F,"envWatcherDebounceMs");const v=6e4;function K(){return t(process.env.CRTR_RECAP_IDLE_MS,v)}e(K,"envRecapIdleMs");function b(){const n=process.env.CRTR_RECAP_MODEL;return n!==void 0&&n.trim()!==""?n.trim():void 0}e(b,"envRecapModelOverride");const f=300*1e3;function k(){return t(process.env.CRTR_BASH_VALVE_MS,f)}e(k,"envBashValveMs");const d=60*1e3;function g(){return t(process.env.CRTR_BASH_AUTO_BG_DEADLINE_MS,d)}e(g,"envBashAutoBgDeadlineMs");function V(){const n=process.env.CRTR_PIDFILE;return n!==void 0&&n!==""?n:void 0}e(V,"envPidfileOverride");const C="@earendil-works/pi-coding-agent";function X(){return process.env.CRTR_BROKER_ENGINE??C}e(X,"envBrokerEngine");function h(){return process.env.CRTR_PI_BINARY}e(h,"envPiBinaryOverride");function w(){return process.env.CRTR_NO_DAEMON_AUTOSTART==="1"}e(w,"envNoDaemonAutostart");function y(){return process.env.CRTRD_TCP}e(y,"envCrtrdTcp");function Y(){const n=process.env.CRTRD_TOKEN;return n!==void 0&&n!==""?n:void 0}e(Y,"envCrtrdToken");function j(){return process.env.CRTR_NO_EXPORTS==="1"}e(j,"envNoExports");function q(){return process.env.CRTR_DEBUG==="1"}e(q,"envDebug");function u(n){if(n===void 0||n==="")return;const r=Number(n);return Number.isSafeInteger(r)&&r>=1?r:void 0}e(u,"parsePositiveInteger");function z(){return u(process.env.CRTR_MAX_LIVE_BROKERS)}e(z,"envMaxLiveBrokers");function J(){return u(process.env.CRTR_WARN_LIVE_BROKERS)}e(J,"envWarnLiveBrokers");function s(n){if(n===void 0)return;const r=Number(n);return Number.isFinite(r)&&r>0?r:void 0}e(s,"parsePositiveMsNoDefault");function Q(){return s(process.env.CRTR_TEST_UNATTENDED_PARK_MS)}e(Q,"envTestUnattendedParkMs");function Z(){return s(process.env.CRTR_UNATTENDED_PARK_MS)}e(Z,"envUnattendedParkMs");function A(){return s(process.env.CRTR_TEST_PARK_SUMMARY_GRACE_MS)}e(A,"envTestParkSummaryGraceMs");const M=5*6e4;function $(){return A()??M}e($,"parkSummaryGraceMs");export{i as INBOX_BETWEEN_TURNS_ENV,g as envBashAutoBgDeadlineMs,k as envBashValveMs,X as envBrokerEngine,y as envCrtrdTcp,Y as envCrtrdToken,q as envDebug,B as envExecutionId,S as envGrantee,l as envHomeOverride,a as envInboxBetweenTurns,z as envMaxLiveBrokers,m as envModelExact,P as envModelIntent,w as envNoDaemonAutostart,j as envNoExports,L as envNodeCwd,c as envNodeId,h as envPiBinaryOverride,V as envPidfileOverride,U as envProfileId,K as envRecapIdleMs,b as envRecapModelOverride,H as envRuntimeHomeOverride,O as envScopes,W as envStreamWatchdogMs,A as envTestParkSummaryGraceMs,Q as envTestUnattendedParkMs,Z as envUnattendedParkMs,J as envWarnLiveBrokers,F as envWatcherDebounceMs,G as envWatcherTickMs,D as isSandboxedNode,$ as parkSummaryGraceMs,I as scopeAllowed};

package/dist/shared/generated-context.js

@@ -1,11 +1,3 @@
-var T=Object.defineProperty;var o=(e,t)=>T(e,"name",{value:t,configurable:!0});const R="crtr-context",_="crtr-situational-context",E="crtr-context-nudge",v="crtr-review-boundary",$="You've stopped but you're not waiting on anyone and haven't finished. Pipe the result to `crtr push final` through a single-quoted heredoc if the work is done, or use `crtr human send` if you are blocked or need the user.",L=`This conversation has been idle with nothing left to wake it, so it is being concluded. This is your last turn. Use it to leave a trustworthy inheritance, not to restart or broaden the work. Do these four things now, then stop.
-
-1. Establish current truth. Check only state that may have changed outside the transcript and matters to resuming\u2014such as the working tree, a remote run, or an external decision. Do not start new work; perform only a quick check needed to avoid recording an unverified claim. If no mandate or work ever began, record that plainly in the inheritance and keep every artifact minimal.
-
-2. Put supporting material in your context directory only when it is needed to keep the inheritance concise. Rewrite existing living documents rather than leave superseded versions. Task state, identifiers, and recovery detail belong here, not in memory.
-
-3. Use memory only for a non-obvious, reusable lesson that should survive this task and is not already recorded. Read \`crtr memory write -h\`, find before writing, and choose the narrowest scope that will reach the next agent who needs it. Do not put a conversation recap, task status, recovery handles, or facts already captured in code or docs into memory.
-
-4. Push exactly one regular update with \`crtr push update --tier deferred\`, never \`crtr push final\`. Write for someone who has not seen this conversation: name the work in plain terms, say where it stands, and say what remains or is blocked. Put the current outcome in the first line; include only needed decisions and recovery handles, then stop.`,N="Provider credentials were just updated (a new login landed). Your previous turn stopped on a provider authentication failure. Continue from where you left off and retry the work that failed.",M="The network connection is back online. Your previous turn stopped on a connection error (the network was down). Continue from where you left off and retry the work that failed.",S="Your previous turn stopped on a provider fault. Continue from where you left off and retry the work that failed.",D="<crtr-review-approval>",j="</crtr-review-approval>",V="<model-fallback-recovery>",F="</model-fallback-recovery>",O='You must submit a result matching the required schema with `crtr push result` before you can stop, or decline it with `crtr push result --decline "<reason>" --code <token>` when the schema cannot be honestly satisfied. You cannot finish or go dormant any other way while this request is pending.\n\nRequired schema:\n\n```json\n',A="\n```";function B(e){return`${O}${e}${A}`}o(B,"formatStructuredOutputReprompt");function X(e,t,n){return n==="credential"?`The previous model (${e}) had no usable provider credential, so you were automatically switched to ${t}. Continue the task from where the failed turn left off.`:`The previous model (${e}) was unavailable (provider 404 not_found), so you were automatically switched to ${t}. Continue the task from where the failed turn left off.`}o(X,"formatModelFallbackRecovery");function x(e){switch(e){case E:return"context-nudge";case R:return"bearings";case v:return"review-boundary";case _:return"situational";default:return}}o(x,"legacyCustomTypeKind");const g=/^[A-Za-z_:][A-Za-z0-9_:.-]*$/,l=/\s+([A-Za-z_:][A-Za-z0-9_:.-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/gy;function k(e){return e.replaceAll("&","&amp;").replaceAll("<","&lt;").replaceAll(">","&gt;").replaceAll('"',"&quot;").replaceAll("'","&apos;")}o(k,"escapeXmlAttribute");function y(e){return e.replaceAll("&","&amp;").replaceAll("<","&lt;").replaceAll(">","&gt;")}o(y,"escapeXmlText");function h(e){return e.replace(/&(?:amp|lt|gt|quot|apos);/g,t=>({"&amp;":"&","&lt;":"<","&gt;":">","&quot;":'"',"&apos;":"'"})[t])}o(h,"unescapeXmlAttribute");function f(e){const t={};l.lastIndex=0;let n=0;for(;n<e.length&&!/^\s*$/.test(e.slice(n));){l.lastIndex=n;const i=l.exec(e);if(i===null)return null;const[,r,a,u]=i;if(r===void 0||Object.hasOwn(t,r))return null;t[r]=h(a??u??""),n=l.lastIndex}return t}o(f,"parseAttributes");function p(e){return Object.entries(e).filter(([,t])=>t!==void 0).map(([t,n])=>{if(!g.test(t))throw new Error(`Invalid XML attribute name: ${t}`);return` ${t}="${k(String(n))}"`}).join("")}o(p,"formatAttributes");function C(e){return typeof e.content=="string"?e.content:Array.isArray(e.content)?e.content.filter(t=>typeof t=="object"&&t!==null&&t.type==="text"&&typeof t.text=="string").map(t=>t.text).join(""):""}o(C,"generatedContextText");function w(e,t,n){if(e==="")throw new Error("Runtime card kind is required");if(Object.hasOwn(t,"kind"))throw new Error("Runtime card facts cannot replace kind");return`<runtime${p({kind:e,...t})}>${n}</runtime>`}o(w,"formatCard");function q(e,t,n){return w(e,t,y(n))}o(q,"formatDataCard");function P(e){const t=[],n=/<from\b([^>]*)>([\s\S]*?)<\/from>/g;for(const i of e.matchAll(n)){const r=f(i[1]??"");if(r?.id===void 0)continue;const a=[],u=i[2]??"",c=/<entry\b([^>]*)>([\s\S]*?)<\/entry>/g;for(const d of u.matchAll(c)){const s=f(d[1]??"");if(s?.kind===void 0)continue;const b=s.disposition==="human-answer"||s.disposition==="human-canceled"?s.disposition:"report";a.push({kind:s.kind,disposition:b,body:h(d[2]??""),...s.ref===void 0?{}:{ref:s.ref}})}const m=r.updates===void 0?Number.NaN:Number(r.updates);t.push({id:r.id,updates:Number.isFinite(m)?m:a.length,finished:r.finished==="true"||a.some(d=>d.kind==="final"),entries:a})}return t}o(P,"parseInboxBody");function U(e,t,n,i){return{kind:e,facts:t,body:n,senders:i}}o(U,"cardFor");function I(e){const t=/^<runtime\b([^>]*)>/.exec(e);if(t===null||!e.endsWith("</runtime>"))return null;const n=f(t[1]??"");if(n?.kind===void 0)return null;const i=e.slice(t[0].length,-10),{kind:r,...a}=n,u=Object.freeze(a),c=r.includes(":")?h(i):i;return U(r,u,c,r==="inbox"?P(c):[])}o(I,"parseEnvelope");function z(e){const t=C(e),n=I(t);if(n!==null)return n;if(e.role!=="custom")return null;const i=x(e.customType);return i===void 0?null:{kind:i,facts:Object.freeze({}),body:t,senders:[]}}o(z,"parseCard");function W(e){return e.startsWith("/")?`Preview only. Read the full body from file \`${e}\`.`:`Read this report with \`crtr canvas history read ${e}\`.`}o(W,"formatInboxRefInstruction");function K(e){const t=e.map(n=>{const i=n.entries.map(r=>{const a=r.disposition==="human-answer"||r.disposition==="human-canceled"?r.disposition:void 0;return`<entry${p({kind:r.kind,ref:r.ref,disposition:a})}>${y(r.body)}</entry>`}).join(`
+var T=Object.defineProperty;var o=(e,t)=>T(e,"name",{value:t,configurable:!0});const v="crtr-context",R="crtr-situational-context",_="crtr-context-nudge",E="crtr-review-boundary",$="You've stopped but you're not waiting on anyone and haven't finished. Pipe the result to `crtr push final` through a single-quoted heredoc if the work is done, or use `crtr human send` if you are blocked or need the user.",L="This conversation has been idle with nothing left to wake it, so it is being concluded. This is your last turn. Use it to leave a trustworthy inheritance, not to restart or broaden the work. Do these four things now, then stop.\n\n1. Establish current truth. Check only state that may have changed outside the transcript and matters to resuming\u2014such as the working tree, a remote run, or an external decision. Do not start new work; perform only a quick check needed to avoid recording an unverified claim. If no mandate or work ever began, record that plainly in the inheritance and keep every artifact minimal.\n\n2. Put supporting material in documents you own (`crtr doc write`) only when it is needed to keep the inheritance concise. Rewrite existing living documents rather than leave superseded versions. Task state, identifiers, and recovery detail belong here, under this node, not under a longer-lived owner.\n\n3. Give a longer-lived owner (`--owner repo|profile|user`) only to a non-obvious, reusable lesson that should survive this task and is not already recorded. Read `crtr doc write -h`, search before writing (`crtr canvas search`), and choose the narrowest owner that will reach the next agent who needs it. Do not put a conversation recap, task status, recovery handles, or facts already captured in code or docs into such a document.\n\n4. Push exactly one regular update with `crtr push update --tier deferred`, never `crtr push final`. Write for someone who has not seen this conversation: name the work in plain terms, say where it stands, and say what remains or is blocked. Put the current outcome in the first line; include only needed decisions and recovery handles, then stop.",N="Provider credentials were just updated (a new login landed). Your previous turn stopped on a provider authentication failure. Continue from where you left off and retry the work that failed.",M="The network connection is back online. Your previous turn stopped on a connection error (the network was down). Continue from where you left off and retry the work that failed.",S="Your previous turn stopped on a provider fault. Continue from where you left off and retry the work that failed.",D="<crtr-review-approval>",j="</crtr-review-approval>",V="<model-fallback-recovery>",F="</model-fallback-recovery>",O='You must submit a result matching the required schema with `crtr push result` before you can stop, or decline it with `crtr push result --decline "<reason>" --code <token>` when the schema cannot be honestly satisfied. You cannot finish or go dormant any other way while this request is pending.\n\nRequired schema:\n\n```json\n',g="\n```";function B(e){return`${O}${e}${g}`}o(B,"formatStructuredOutputReprompt");function X(e,t,n){return n==="credential"?`The previous model (${e}) had no usable provider credential, so you were automatically switched to ${t}. Continue the task from where the failed turn left off.`:`The previous model (${e}) was unavailable (provider 404 not_found), so you were automatically switched to ${t}. Continue the task from where the failed turn left off.`}o(X,"formatModelFallbackRecovery");function A(e){switch(e){case _:return"context-nudge";case v:return"bearings";case E:return"review-boundary";case R:return"situational";default:return}}o(A,"legacyCustomTypeKind");const x=/^[A-Za-z_:][A-Za-z0-9_:.-]*$/,l=/\s+([A-Za-z_:][A-Za-z0-9_:.-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/gy;function k(e){return e.replaceAll("&","&amp;").replaceAll("<","&lt;").replaceAll(">","&gt;").replaceAll('"',"&quot;").replaceAll("'","&apos;")}o(k,"escapeXmlAttribute");function w(e){return e.replaceAll("&","&amp;").replaceAll("<","&lt;").replaceAll(">","&gt;")}o(w,"escapeXmlText");function h(e){return e.replace(/&(?:amp|lt|gt|quot|apos);/g,t=>({"&amp;":"&","&lt;":"<","&gt;":">","&quot;":'"',"&apos;":"'"})[t])}o(h,"unescapeXmlAttribute");function f(e){const t={};l.lastIndex=0;let n=0;for(;n<e.length&&!/^\s*$/.test(e.slice(n));){l.lastIndex=n;const i=l.exec(e);if(i===null)return null;const[,r,a,u]=i;if(r===void 0||Object.hasOwn(t,r))return null;t[r]=h(a??u??""),n=l.lastIndex}return t}o(f,"parseAttributes");function p(e){return Object.entries(e).filter(([,t])=>t!==void 0).map(([t,n])=>{if(!x.test(t))throw new Error(`Invalid XML attribute name: ${t}`);return` ${t}="${k(String(n))}"`}).join("")}o(p,"formatAttributes");function C(e){return typeof e.content=="string"?e.content:Array.isArray(e.content)?e.content.filter(t=>typeof t=="object"&&t!==null&&t.type==="text"&&typeof t.text=="string").map(t=>t.text).join(""):""}o(C,"generatedContextText");function y(e,t,n){if(e==="")throw new Error("Runtime card kind is required");if(Object.hasOwn(t,"kind"))throw new Error("Runtime card facts cannot replace kind");return`<runtime${p({kind:e,...t})}>${n}</runtime>`}o(y,"formatCard");function q(e,t,n){return y(e,t,w(n))}o(q,"formatDataCard");function P(e){const t=[],n=/<from\b([^>]*)>([\s\S]*?)<\/from>/g;for(const i of e.matchAll(n)){const r=f(i[1]??"");if(r?.id===void 0)continue;const a=[],u=i[2]??"",c=/<entry\b([^>]*)>([\s\S]*?)<\/entry>/g;for(const d of u.matchAll(c)){const s=f(d[1]??"");if(s?.kind===void 0)continue;const b=s.disposition==="human-answer"||s.disposition==="human-canceled"?s.disposition:"report";a.push({kind:s.kind,disposition:b,body:h(d[2]??""),...s.ref===void 0?{}:{ref:s.ref}})}const m=r.updates===void 0?Number.NaN:Number(r.updates);t.push({id:r.id,updates:Number.isFinite(m)?m:a.length,finished:r.finished==="true"||a.some(d=>d.kind==="final"),entries:a})}return t}o(P,"parseInboxBody");function U(e,t,n,i){return{kind:e,facts:t,body:n,senders:i}}o(U,"cardFor");function I(e){const t=/^<runtime\b([^>]*)>/.exec(e);if(t===null||!e.endsWith("</runtime>"))return null;const n=f(t[1]??"");if(n?.kind===void 0)return null;const i=e.slice(t[0].length,-10),{kind:r,...a}=n,u=Object.freeze(a),c=r.includes(":")?h(i):i;return U(r,u,c,r==="inbox"?P(c):[])}o(I,"parseEnvelope");function z(e){const t=C(e),n=I(t);if(n!==null)return n;if(e.role!=="custom")return null;const i=A(e.customType);return i===void 0?null:{kind:i,facts:Object.freeze({}),body:t,senders:[]}}o(z,"parseCard");function W(e){return e.startsWith("/")?`Preview only. Read the full body from file \`${e}\`.`:`Read this report with \`crtr canvas read ${e}\`.`}o(W,"formatInboxRefInstruction");function K(e){const t=e.map(n=>{const i=n.entries.map(r=>{const a=r.disposition==="human-answer"||r.disposition==="human-canceled"?r.disposition:void 0;return`<entry${p({kind:r.kind,ref:r.ref,disposition:a})}>${w(r.body)}</entry>`}).join(`
 `);return`<from${p({id:n.id})}>${i}</from>`}).join(`
-`);return w("inbox",{},t)}o(K,"formatInboxCard");export{N as AUTH_FAULT_RECOVERY_BODY,M as CONNECTION_FAULT_RECOVERY_BODY,R as CONTEXT_INTRO_CUSTOM_TYPE,E as CONTEXT_NUDGE_CUSTOM_TYPE,L as PARK_SUMMARY_PROMPT,S as PROVIDER_FAULT_RECOVERY_BODY,v as REVIEW_BOUNDARY_CUSTOM_TYPE,_ as SITUATIONAL_CONTEXT_CUSTOM_TYPE,$ as STALL_REPROMPT,w as formatCard,q as formatDataCard,K as formatInboxCard,W as formatInboxRefInstruction,X as formatModelFallbackRecovery,B as formatStructuredOutputReprompt,C as generatedContextText,z as parseCard};
+`);return y("inbox",{},t)}o(K,"formatInboxCard");export{N as AUTH_FAULT_RECOVERY_BODY,M as CONNECTION_FAULT_RECOVERY_BODY,v as CONTEXT_INTRO_CUSTOM_TYPE,_ as CONTEXT_NUDGE_CUSTOM_TYPE,L as PARK_SUMMARY_PROMPT,S as PROVIDER_FAULT_RECOVERY_BODY,E as REVIEW_BOUNDARY_CUSTOM_TYPE,R as SITUATIONAL_CONTEXT_CUSTOM_TYPE,$ as STALL_REPROMPT,y as formatCard,q as formatDataCard,K as formatInboxCard,W as formatInboxRefInstruction,X as formatModelFallbackRecovery,B as formatStructuredOutputReprompt,C as generatedContextText,z as parseCard};

package/dist/shared/inbox-entry-body.d.ts

@@ -0,0 +1,22 @@
+export declare const INLINE_REPORT_MAX_CHARS = 1000;
+/** The rendering fields both inbox projections share. */
+export interface InboxEntryFields {
+    ts: string;
+    from: string | null;
+    from_name?: string;
+    label: string;
+    ref?: string;
+    data?: Record<string, unknown>;
+}
+/** A report document's ref (`<node>/reports/<name>`), else undefined. */
+export declare function reportRefNodeId(ref: string | undefined): string | undefined;
+/** Clip a body to the bounded preview stored beside a spilled message body. */
+export declare function clipBody(body: string): {
+    text: string;
+    clipped: boolean;
+};
+export declare function inlineBody(entry: Pick<InboxEntryFields, 'data' | 'label'>): string;
+/** One entry's card body: an inlined short report, a bounded inline message body, an event
+ *  push rendered from its metadata, or the label. `report` is the report document's body when
+ *  the caller could read it. */
+export declare function renderEntryBody(entry: InboxEntryFields, report: string | null): string;

package/dist/shared/inbox-entry-body.js

@@ -0,0 +1,10 @@
+var p=Object.defineProperty;var i=(e,t)=>p(e,"name",{value:t,configurable:!0});import{formatInboxRefInstruction as $}from"./generated-context.js";const l=12,f=1e3,j=1e3;function k(e){return(e===void 0?null:/^([a-z0-9-]+)\/reports\/[^/]+$/.exec(e))?.[1]}i(k,"reportRefNodeId");function h(e){let t=e,r=!1;const o=t.split(`
+`);return o.length>l&&(t=o.slice(0,l).join(`
+`),r=!0),t.length>f&&(t=t.slice(0,f),r=!0),{text:t.trimEnd(),clipped:r}}i(h,"clipBody");function y(e){const t=typeof e.data?.body=="string"?String(e.data.body).trim():"";return t===""||t===e.label?"":t}i(y,"inlineBody");function x(e){const t=e.data?.push;return typeof t=="object"&&t!==null&&typeof t.event=="string"?t:null}i(x,"pushOf");function v(e){return e.type==="document"?`[[${e.owner===null?e.name:`${e.owner}/${e.name}`}]]`:e.type==="job"?`job ${e.id} (\`${e.name}\`)`:e.type==="node"?`node ${e.name} (${e.id})`:`${e.type} ${e.name}`}i(v,"objectText");function _(e,t){return t.actor===null?"the runtime":e.from_name===void 0||e.from_name===t.actor?t.actor:`${e.from_name} (${t.actor})`}i(_,"actorText");function u(e){return Array.isArray(e)?e.filter(t=>typeof t=="string"):[]}i(u,"list");function R(e,t){const r=v(t.object),o=_(e,t),n=t.attrs,a=t.object.type==="document"?` Read it with \`crtr canvas read ${t.object.owner===null?t.object.name:`${t.object.owner}/${t.object.name}`}\`.`:"";switch(t.event){case"created":return t.object.type==="node"?`${o} created ${r}${typeof n.kind=="string"?`, kind ${n.kind}`:""}.`:`${o} created ${r}.${a}`;case"read":return`${o} read ${r}.`;case"watched":return`${o} started watching ${r}.`;case"deleted":return`${o} deleted ${r}.`;case"edited":{const c=u(n.authors),d=u(n.rationales),s=typeof n.from_revision=="number"&&typeof n.revision=="number"&&n.revision-n.from_revision>1?`revisions ${n.from_revision+1}\u2013${n.revision}`:typeof n.revision=="number"?`revision ${n.revision}`:"a new revision",m=c.length===0?o:c.join(", "),b=d.length===0?"":` Rationale: ${d.join("; ")}.`,g=n.needs_merge===!0?" Two edits were made from the same revision; read it and edit it to merge them.":"",w=` You get this because you read or wrote it; if it no longer concerns your work, stop with \`crtr canvas unwatch ${t.object.owner===null?t.object.name:`${t.object.owner}/${t.object.name}`}\`.`;return`${m} edited ${r} (${s}).${b}${g}${a}${w}`}case"messaged":return`${o} messaged ${r}.`;case"sent":return`${o} sent a message as ${r}.`;case"configured":return`${o} changed the settings of ${r}${typeof n.changed=="string"?`: ${n.changed}`:""}.`;case"exited":return`${r[0].toUpperCase()}${r.slice(1)} exited with code ${String(n["exit-code"])}. Log: ${String(n["log-path"])}`;case"killed":{const c=t.actor===null?"":` by ${o}`,d=typeof n.reason=="string"?` (${n.reason})`:"",s=n.reason==="deadline"?` It was canceled at its deadline; claim it with \`crtr node bash extend ${t.object.id} --for <duration>\` next time.`:"";return`${r[0].toUpperCase()}${r.slice(1)} was killed${c}${d}.${s} Log: ${String(n["log-path"])}`}default:return e.label}}i(R,"renderPush");function E(e,t){if(t!==null&&t.length<j&&e.ref!==void 0)return`${t.trimEnd()}
+
+${$(e.ref)}`;const r=y(e);if(r===""){const a=x(e);return a!==null&&e.ref===void 0?R(e,a):e.ref===void 0?e.label:`${e.label}
+
+${$(e.ref)}`}const{text:o,clipped:n}=h(r);return e.ref!==void 0?`${o}
+
+${$(e.ref)}`:n?`${o}
+\u2026 (body clipped)`:o}i(E,"renderEntryBody");export{j as INLINE_REPORT_MAX_CHARS,h as clipBody,y as inlineBody,E as renderEntryBody,k as reportRefNodeId};

package/dist/{core/memory → shared}/inline-ref-guidance.d.ts

@@ -1,6 +1,6 @@
 /**
- * Resolve every slash token in `text` against `names` (the exact canonical
- * `buildRefInventory().names` set), collapse duplicates, and return one
+ * Resolve every slash token in `text` against `names` (the node's document
+ * names from the delivery route), collapse duplicates, and return one
  * directive line per distinct resolved ref in FIRST-APPEARANCE order.
  * Returns `null` when no token resolves, so the broker sends no guidance
  * message for prose with no refs.

package/dist/shared/inline-ref-guidance.js

@@ -0,0 +1,2 @@
+var a=Object.defineProperty;var o=(n,t)=>a(n,"name",{value:t,configurable:!0});import{findRefTokens as s}from"./inline-ref-grammar.js";const r="The user explicitly called out specific documents. Read the relevant mentioned documents:";function f(n,t){const i=new Set,c=[];for(const e of s(n))i.has(e.candidate)||t.has(e.candidate)&&(i.add(e.candidate),c.push(e.candidate));if(c.length===0)return null;const d=c.map(e=>`- crtr canvas read ${e}`);return[r,...d].join(`
+`)}o(f,"buildGuidance");export{f as buildGuidance};

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import type { BindingId } from './core/keybindings/catalog.js';
-import type { ProfileProject } from './api/dto/profiles.js';
+import type { DeliveryLimits, ProfileProject } from './api/dto/profiles.js';
 export type Scope = 'user' | 'project' | 'builtin';
 export declare const ExitCode: {
     readonly SUCCESS: 0;
@@ -511,6 +511,8 @@ export interface ProfileManifest {
      *  every broker launched under the profile as `CRTR_PROFILE_META_<KEY>`
      *  env (see `core/runtime/spawn-env.ts`). Absent means none. */
     metadata?: Record<string, string>;
+    /** Per-owner delivery caps; absent means none. */
+    delivery_limits?: DeliveryLimits;
     /** App that owns this profile; older terminal profiles have no grantee. */
     grantee?: string;
     created_at: string;

package/docs/cli/memory-and-preferences.md

@@ -1,11 +1,11 @@
 ---
 title: Memory and preferences
-description: When you want later agents to retain a fact or follow an instruction, read this page because it explains where memory is stored and how to inspect or revise it.
+description: When you want later agents to retain a fact or follow an instruction, read this page because it explains who owns a saved document and how to inspect or revise it.
 ---
 
 # Memory and preferences
 
-You can give future agents useful context without pasting the same background into every conversation. Ask an agent to remember a durable fact or instruction, then inspect the saved memory yourself from the terminal.
+You can give future agents useful context without pasting the same background into every conversation. Ask an agent to remember a durable fact or instruction, then inspect the saved document yourself from the terminal.
 
 ## Tell an agent what should persist
 
@@ -18,35 +18,33 @@ Say what should be remembered and where it applies.
 | Something for every project you use | “Remember this as a user preference.” |
 | Something only agents in this repository need | “Remember this for this project.” |
 
-A preference tells an agent how to act. Knowledge gives it facts or a procedure to consult. The narrowest useful store is best: a user memory follows you everywhere, while a project memory belongs to one repository. For the explanation of memory tiers and loading, see [Memory](../concepts/memory.md).
+A preference tells an agent how to act. Knowledge gives it facts or a procedure to consult. The narrowest useful owner is best: a document you own follows you everywhere, while a document a repository owns belongs to that one repository. For the explanation of document owners and loading, see [Documents](../concepts/memory.md).
 
 ## Browse what was saved
 
-List the memory documents available in your current context:
+List the documents available in your current context:
 
 ```sh
-crtr memory list
+crtr canvas list --type document
 ```
 
 Read one by its name from that list:
 
 ```sh
-crtr memory read <name>
+crtr canvas read <name>
 ```
 
-`crtr memory read` resolves the current winning document when the same name exists at more than one scope. Add `--scope user` to read only user memory, or `--dir <project-directory>` to inspect one exact project store.
+`crtr canvas read` resolves a bare name in your view, nearest owner first. Write `<owner>/<name>` to read one owner's document, and `crtr canvas search` to find one by its text.
 
-## Edit a memory document
+## Edit a document
 
-Memory revisions are intentional and recorded. To replace a document's body, pipe the complete replacement text to `crtr memory edit` and give the reason for the revision:
+Document revisions are intentional and recorded. To replace a document's body, pipe the complete replacement text to `crtr doc edit` and give the reason for the revision:
 
 ```sh
 printf '%s\n' 'Production changes need an explicit approval.' | \
-  crtr memory edit <name> --rationale "Updated the approval rule."
+  crtr doc edit <name> --rationale "Updated the approval rule."
 ```
 
-`crtr memory edit` replaces the whole body you pipe; it does not append text. Use `crtr memory history <name>` to read the revision history. If you want to create a document yourself, use `crtr memory write`; it requires a kind, a routing sentence that tells agents when to read it, and the document body. New documents persist `privacy: public` unless `--privacy friends` or `--privacy private` is supplied. `crtr memory edit --privacy <level>` changes the level and records the revision. Older documents without the field read as private until edited or migrated. Privacy levels are metadata; crouter does not yet enforce app read or write access by level.
+`crtr doc edit` replaces the whole body you pipe; it does not append text, and `--replace '[{"old":"…","new":"…"}]'` changes only the named passages. Read the document before you edit it; an edit made from an older revision is refused. Use `crtr doc history <name>` to read the revision history. If you want to create a document yourself, use `crtr doc write`; it requires a kind, a preview sentence that tells agents when to read it, and the document body, and `--owner user|repo|profile` chooses who owns it. New documents are `privacy: public` unless `--privacy friends` or `--privacy private` is supplied; a repository owns only public documents. `crtr doc edit --privacy <level>` changes the level and records the revision.
 
-To set every existing user and profile memory document to public after updating crouter, run `npm run build && node scripts/migrate-memory-privacy.mjs` from the crouter repository. Each changed document gets an ordinary edit history record with rationale `privacy rollout: Silas's memories default to public`. The command excludes project, node, builtin, and plugin stores and leaves documents already marked public unchanged. It does not run automatically.
-
-Memory is for reusable current truth and durable instructions, not a transcript of one conversation. When a fact changes, update the existing document rather than saving a second version.
+Documents are for reusable current truth and durable instructions, not a transcript of one conversation. When a fact changes, update the existing document rather than saving a second version.

package/docs/concepts/README.md

@@ -11,7 +11,7 @@ Use these pages to choose the shape of an agent application before you start wir
 |---|---|
 | [Nodes and the canvas](./nodes-and-the-canvas.md) | Whether work needs a durable node rather than one request and response |
 | [Lifecycle and wakes](./lifecycle-and-wakes.md) | Whether a node should finish, remain resident, delegate, or wait |
-| [Memory](./memory.md) | What an agent should know or embody, who owns it, and where it belongs |
+| [Documents](./memory.md) | What an agent should know or embody, who owns it, and where it belongs |
 | [Profiles, kinds, and modes](./profiles-kinds-and-modes.md) | Which run-shaping dial matches an application concern |
 | [Scopes and trust](./scopes-and-trust.md) | What an application or node may do and why only the daemon writes canvas state |
 | [Why a daemon](./why-a-daemon.md) | Why a broker survives a terminal and why viewers are clients rather than hosts |