[{"data":1,"prerenderedAt":1046},["ShallowReactive",2],{"docs-\u002Fdocs\u002Fv2\u002Ftui\u002Fapi\u002Fagents":3},{"id":4,"title":5,"body":6,"description":1039,"extension":1040,"meta":1041,"navigation":156,"path":1042,"seo":1043,"stem":1044,"__hash__":1045},"docs\u002Fdocs\u002Fv2\u002Ftui\u002Fapi\u002Fagents.md","agents",{"type":7,"value":8,"toc":1031},"minimark",[9,12,25,490,495,571,584,593,597,630,639,646,650,696,699,703,900,906,909,971,978,982,1027],[10,11,5],"h1",{"id":5},[13,14,15,16,20,21,24],"p",{},"Running instances. You ",[17,18,19],"strong",{},"start by name"," and then address ",[17,22,23],{},"by instance"," — one agent can\nhave many live instances, so a verb taking a name has no answer for \"which one\".",[26,27,32],"pre",{"className":28,"code":29,"language":30,"meta":31,"style":31},"language-ts shiki shiki-themes dark-plus","interface AgentsApi {\n    \u002F\u002F Reading.\n    targets(): Promise\u003Creadonly AgentTarget[]>   \u002F\u002F everything that can be started\n    list(): readonly AgentInstance[]             \u002F\u002F running, in spawn order\n    get(id: string): AgentInstance | null\n    focused(): AgentInstance | null\n\n    \u002F\u002F Lifecycle. Throws INSTANCE_NOT_RUNNING on an id nothing answers to.\n    spawn(name: string): Promise\u003CAgentInstance>   \u002F\u002F always NEW, in the background\n    focus(id: string): void\n    stop(id?: string): Promise\u003Cvoid>     \u002F\u002F omit id for the focused instance\n    reboot(id?: string): Promise\u003Cvoid>   \u002F\u002F omit id for the focused instance\n\n    \u002F\u002F Conversation.\n    send(content: string): Promise\u003Cvoid>   \u002F\u002F to the FOCUSED instance. Yields nothing.\n    interrupt(): boolean\n}\n\ntype AgentInstance = {\n    readonly id: string        \u002F\u002F stable; every verb addresses by this\n    readonly name: string      \u002F\u002F the project — several instances may share one\n    readonly focused: boolean\n    readonly activity: \"booting\" | \"rebooting\" | \"shutting-down\" | \"working\" | null\n}\n\ntype AgentTarget = {\n    readonly name: string\n    readonly kind: \"local\" | \"deployed\"\n    readonly instances: readonly AgentInstance[]   \u002F\u002F most recently focused first\n}\n","ts","",[33,34,35,52,59,87,106,137,151,158,164,193,212,242,268,273,279,307,318,324,329,340,356,371,383,416,421,426,435,447,465,485],"code",{"__ignoreMap":31},[36,37,40,44,48],"span",{"class":38,"line":39},"line",1,[36,41,43],{"class":42},"scz_3","interface",[36,45,47],{"class":46},"sNl3T"," AgentsApi",[36,49,51],{"class":50},"sTNBD"," {\n",[36,53,55],{"class":38,"line":54},2,[36,56,58],{"class":57},"sOLPB","    \u002F\u002F Reading.\n",[36,60,62,66,69,72,75,78,81,84],{"class":38,"line":61},3,[36,63,65],{"class":64},"sCudf","    targets",[36,67,68],{"class":50},"(): ",[36,70,71],{"class":46},"Promise",[36,73,74],{"class":50},"\u003C",[36,76,77],{"class":42},"readonly",[36,79,80],{"class":46}," AgentTarget",[36,82,83],{"class":50},"[]>   ",[36,85,86],{"class":57},"\u002F\u002F everything that can be started\n",[36,88,90,93,95,97,100,103],{"class":38,"line":89},4,[36,91,92],{"class":64},"    list",[36,94,68],{"class":50},[36,96,77],{"class":42},[36,98,99],{"class":46}," AgentInstance",[36,101,102],{"class":50},"[]             ",[36,104,105],{"class":57},"\u002F\u002F running, in spawn order\n",[36,107,109,112,115,119,122,125,128,131,134],{"class":38,"line":108},5,[36,110,111],{"class":64},"    get",[36,113,114],{"class":50},"(",[36,116,118],{"class":117},"s3F5K","id",[36,120,121],{"class":50},": ",[36,123,124],{"class":46},"string",[36,126,127],{"class":50},"): ",[36,129,130],{"class":46},"AgentInstance",[36,132,133],{"class":50}," | ",[36,135,136],{"class":46},"null\n",[36,138,140,143,145,147,149],{"class":38,"line":139},6,[36,141,142],{"class":64},"    focused",[36,144,68],{"class":50},[36,146,130],{"class":46},[36,148,133],{"class":50},[36,150,136],{"class":46},[36,152,154],{"class":38,"line":153},7,[36,155,157],{"emptyLinePlaceholder":156},true,"\n",[36,159,161],{"class":38,"line":160},8,[36,162,163],{"class":57},"    \u002F\u002F Lifecycle. Throws INSTANCE_NOT_RUNNING on an id nothing answers to.\n",[36,165,167,170,172,175,177,179,181,183,185,187,190],{"class":38,"line":166},9,[36,168,169],{"class":64},"    spawn",[36,171,114],{"class":50},[36,173,174],{"class":117},"name",[36,176,121],{"class":50},[36,178,124],{"class":46},[36,180,127],{"class":50},[36,182,71],{"class":46},[36,184,74],{"class":50},[36,186,130],{"class":46},[36,188,189],{"class":50},">   ",[36,191,192],{"class":57},"\u002F\u002F always NEW, in the background\n",[36,194,196,199,201,203,205,207,209],{"class":38,"line":195},10,[36,197,198],{"class":64},"    focus",[36,200,114],{"class":50},[36,202,118],{"class":117},[36,204,121],{"class":50},[36,206,124],{"class":46},[36,208,127],{"class":50},[36,210,211],{"class":46},"void\n",[36,213,215,218,220,222,225,227,229,231,233,236,239],{"class":38,"line":214},11,[36,216,217],{"class":64},"    stop",[36,219,114],{"class":50},[36,221,118],{"class":117},[36,223,224],{"class":50},"?: ",[36,226,124],{"class":46},[36,228,127],{"class":50},[36,230,71],{"class":46},[36,232,74],{"class":50},[36,234,235],{"class":46},"void",[36,237,238],{"class":50},">     ",[36,240,241],{"class":57},"\u002F\u002F omit id for the focused instance\n",[36,243,245,248,250,252,254,256,258,260,262,264,266],{"class":38,"line":244},12,[36,246,247],{"class":64},"    reboot",[36,249,114],{"class":50},[36,251,118],{"class":117},[36,253,224],{"class":50},[36,255,124],{"class":46},[36,257,127],{"class":50},[36,259,71],{"class":46},[36,261,74],{"class":50},[36,263,235],{"class":46},[36,265,189],{"class":50},[36,267,241],{"class":57},[36,269,271],{"class":38,"line":270},13,[36,272,157],{"emptyLinePlaceholder":156},[36,274,276],{"class":38,"line":275},14,[36,277,278],{"class":57},"    \u002F\u002F Conversation.\n",[36,280,282,285,287,290,292,294,296,298,300,302,304],{"class":38,"line":281},15,[36,283,284],{"class":64},"    send",[36,286,114],{"class":50},[36,288,289],{"class":117},"content",[36,291,121],{"class":50},[36,293,124],{"class":46},[36,295,127],{"class":50},[36,297,71],{"class":46},[36,299,74],{"class":50},[36,301,235],{"class":46},[36,303,189],{"class":50},[36,305,306],{"class":57},"\u002F\u002F to the FOCUSED instance. Yields nothing.\n",[36,308,310,313,315],{"class":38,"line":309},16,[36,311,312],{"class":64},"    interrupt",[36,314,68],{"class":50},[36,316,317],{"class":46},"boolean\n",[36,319,321],{"class":38,"line":320},17,[36,322,323],{"class":50},"}\n",[36,325,327],{"class":38,"line":326},18,[36,328,157],{"emptyLinePlaceholder":156},[36,330,332,335,337],{"class":38,"line":331},19,[36,333,334],{"class":42},"type",[36,336,99],{"class":46},[36,338,339],{"class":50}," = {\n",[36,341,343,346,349,351,353],{"class":38,"line":342},20,[36,344,345],{"class":42},"    readonly",[36,347,348],{"class":117}," id",[36,350,121],{"class":50},[36,352,124],{"class":46},[36,354,355],{"class":57},"        \u002F\u002F stable; every verb addresses by this\n",[36,357,359,361,364,366,368],{"class":38,"line":358},21,[36,360,345],{"class":42},[36,362,363],{"class":117}," name",[36,365,121],{"class":50},[36,367,124],{"class":46},[36,369,370],{"class":57},"      \u002F\u002F the project — several instances may share one\n",[36,372,374,376,379,381],{"class":38,"line":373},22,[36,375,345],{"class":42},[36,377,378],{"class":117}," focused",[36,380,121],{"class":50},[36,382,317],{"class":46},[36,384,386,388,391,393,397,399,402,404,407,409,412,414],{"class":38,"line":385},23,[36,387,345],{"class":42},[36,389,390],{"class":117}," activity",[36,392,121],{"class":50},[36,394,396],{"class":395},"sKc5r","\"booting\"",[36,398,133],{"class":50},[36,400,401],{"class":395},"\"rebooting\"",[36,403,133],{"class":50},[36,405,406],{"class":395},"\"shutting-down\"",[36,408,133],{"class":50},[36,410,411],{"class":395},"\"working\"",[36,413,133],{"class":50},[36,415,136],{"class":46},[36,417,419],{"class":38,"line":418},24,[36,420,323],{"class":50},[36,422,424],{"class":38,"line":423},25,[36,425,157],{"emptyLinePlaceholder":156},[36,427,429,431,433],{"class":38,"line":428},26,[36,430,334],{"class":42},[36,432,80],{"class":46},[36,434,339],{"class":50},[36,436,438,440,442,444],{"class":38,"line":437},27,[36,439,345],{"class":42},[36,441,363],{"class":117},[36,443,121],{"class":50},[36,445,446],{"class":46},"string\n",[36,448,450,452,455,457,460,462],{"class":38,"line":449},28,[36,451,345],{"class":42},[36,453,454],{"class":117}," kind",[36,456,121],{"class":50},[36,458,459],{"class":395},"\"local\"",[36,461,133],{"class":50},[36,463,464],{"class":395},"\"deployed\"\n",[36,466,468,470,473,475,477,479,482],{"class":38,"line":467},29,[36,469,345],{"class":42},[36,471,472],{"class":117}," instances",[36,474,121],{"class":50},[36,476,77],{"class":42},[36,478,99],{"class":46},[36,480,481],{"class":50},"[]   ",[36,483,484],{"class":57},"\u002F\u002F most recently focused first\n",[36,486,488],{"class":38,"line":487},30,[36,489,323],{"class":50},[491,492,494],"h2",{"id":493},"spawn-focus-send","Spawn, focus, send",[26,496,498],{"className":28,"code":497,"language":30,"meta":31,"style":31},"const reviewer = await agents.spawn(\"@axon\u002Freviewer\")\nagents.focus(reviewer.id)\nawait agents.send(\"review main\")\n",[33,499,500,533,553],{"__ignoreMap":31},[36,501,502,505,509,512,516,519,522,525,527,530],{"class":38,"line":39},[36,503,504],{"class":42},"const",[36,506,508],{"class":507},"s9McN"," reviewer",[36,510,511],{"class":50}," = ",[36,513,515],{"class":514},"sYbnZ","await",[36,517,518],{"class":117}," agents",[36,520,521],{"class":50},".",[36,523,524],{"class":64},"spawn",[36,526,114],{"class":50},[36,528,529],{"class":395},"\"@axon\u002Freviewer\"",[36,531,532],{"class":50},")\n",[36,534,535,537,539,542,544,547,549,551],{"class":38,"line":54},[36,536,5],{"class":117},[36,538,521],{"class":50},[36,540,541],{"class":64},"focus",[36,543,114],{"class":50},[36,545,546],{"class":117},"reviewer",[36,548,521],{"class":50},[36,550,118],{"class":117},[36,552,532],{"class":50},[36,554,555,557,559,561,564,566,569],{"class":38,"line":61},[36,556,515],{"class":514},[36,558,518],{"class":117},[36,560,521],{"class":50},[36,562,563],{"class":64},"send",[36,565,114],{"class":50},[36,567,568],{"class":395},"\"review main\"",[36,570,532],{"class":50},[13,572,573,575,576,579,580,583],{},[33,574,524],{}," runs in the ",[17,577,578],{},"background"," and does not take the screen — a config booting two\nagents would otherwise have them race for it, and neither asked to be looked at. It\nreturns the instance because ",[33,581,582],{},"a.id !== b.id"," for two spawns of the same agent: \"the one I\njust started\" cannot be recovered from the name.",[13,585,586,588,589,592],{},[33,587,563],{}," targets whatever is ",[17,590,591],{},"focused",", which is why the middle line is required.",[491,594,596],{"id":595},"send-yields-nothing-deliberately","send yields nothing, deliberately",[26,598,600],{"className":28,"code":599,"language":30,"meta":31,"style":31},"const reply = await agents.send(\"what changed?\")   \u002F\u002F void\n",[33,601,602],{"__ignoreMap":31},[36,603,604,606,609,611,613,615,617,619,621,624,627],{"class":38,"line":39},[36,605,504],{"class":42},[36,607,608],{"class":507}," reply",[36,610,511],{"class":50},[36,612,515],{"class":514},[36,614,518],{"class":117},[36,616,521],{"class":50},[36,618,563],{"class":64},[36,620,114],{"class":50},[36,622,623],{"class":395},"\"what changed?\"",[36,625,626],{"class":50},")   ",[36,628,629],{"class":57},"\u002F\u002F void\n",[13,631,632,633,638],{},"An extension drives a conversation and never consumes one. Branching on model output is\nan agent's job — build a ",[634,635,637],"a",{"href":636},"\u002Fdocs\u002Fv2\u002Fcognets","cognet",". Enforced by the type.",[13,640,641,642,645],{},"A send during a switch is queued for the agent ",[17,643,644],{},"arriving",", not delivered to the one\nbeing left.",[491,647,649],{"id":648},"stop-vs-reboot","stop vs reboot",[26,651,653],{"className":28,"code":652,"language":30,"meta":31,"style":31},"await agents.reboot(id)   \u002F\u002F rescan + hot-swap. The conversation survives.\nawait agents.stop(id)     \u002F\u002F the only verb here that ends a conversation.\n",[33,654,655,675],{"__ignoreMap":31},[36,656,657,659,661,663,666,668,670,672],{"class":38,"line":39},[36,658,515],{"class":514},[36,660,518],{"class":117},[36,662,521],{"class":50},[36,664,665],{"class":64},"reboot",[36,667,114],{"class":50},[36,669,118],{"class":117},[36,671,626],{"class":50},[36,673,674],{"class":57},"\u002F\u002F rescan + hot-swap. The conversation survives.\n",[36,676,677,679,681,683,686,688,690,693],{"class":38,"line":54},[36,678,515],{"class":514},[36,680,518],{"class":117},[36,682,521],{"class":50},[36,684,685],{"class":64},"stop",[36,687,114],{"class":50},[36,689,118],{"class":117},[36,691,692],{"class":50},")     ",[36,694,695],{"class":57},"\u002F\u002F the only verb here that ends a conversation.\n",[13,697,698],{},"Focusing never stops what you were on.",[491,700,702],{"id":701},"acting-on-what-is-running","Acting on what is running",[26,704,706],{"className":28,"code":705,"language":30,"meta":31,"style":31},"commands.register(\"stop all\", {\n    async run() {\n        const running = agents.list()\n        if (!running.length) return tui.info(\"nothing running\")\n        if (!await palette.confirm(`Stop ${running.length} instances?`)) return\n\n        for (const i of running) await agents.stop(i.id)\n    },\n    description: \"Shut down every instance\",\n})\n",[33,707,708,726,737,757,794,836,840,879,884,895],{"__ignoreMap":31},[36,709,710,713,715,718,720,723],{"class":38,"line":39},[36,711,712],{"class":117},"commands",[36,714,521],{"class":50},[36,716,717],{"class":64},"register",[36,719,114],{"class":50},[36,721,722],{"class":395},"\"stop all\"",[36,724,725],{"class":50},", {\n",[36,727,728,731,734],{"class":38,"line":54},[36,729,730],{"class":42},"    async",[36,732,733],{"class":64}," run",[36,735,736],{"class":50},"() {\n",[36,738,739,742,745,747,749,751,754],{"class":38,"line":61},[36,740,741],{"class":42},"        const",[36,743,744],{"class":507}," running",[36,746,511],{"class":50},[36,748,5],{"class":117},[36,750,521],{"class":50},[36,752,753],{"class":64},"list",[36,755,756],{"class":50},"()\n",[36,758,759,762,765,768,770,773,776,779,782,784,787,789,792],{"class":38,"line":89},[36,760,761],{"class":514},"        if",[36,763,764],{"class":50}," (!",[36,766,767],{"class":117},"running",[36,769,521],{"class":50},[36,771,772],{"class":117},"length",[36,774,775],{"class":50},") ",[36,777,778],{"class":514},"return",[36,780,781],{"class":117}," tui",[36,783,521],{"class":50},[36,785,786],{"class":64},"info",[36,788,114],{"class":50},[36,790,791],{"class":395},"\"nothing running\"",[36,793,532],{"class":50},[36,795,796,798,800,802,805,807,810,812,815,818,820,822,824,827,830,833],{"class":38,"line":108},[36,797,761],{"class":514},[36,799,764],{"class":50},[36,801,515],{"class":514},[36,803,804],{"class":117}," palette",[36,806,521],{"class":50},[36,808,809],{"class":64},"confirm",[36,811,114],{"class":50},[36,813,814],{"class":395},"`Stop ",[36,816,817],{"class":42},"${",[36,819,767],{"class":117},[36,821,521],{"class":50},[36,823,772],{"class":117},[36,825,826],{"class":42},"}",[36,828,829],{"class":395}," instances?`",[36,831,832],{"class":50},")) ",[36,834,835],{"class":514},"return\n",[36,837,838],{"class":38,"line":139},[36,839,157],{"emptyLinePlaceholder":156},[36,841,842,845,848,850,853,856,858,860,862,864,866,868,870,873,875,877],{"class":38,"line":153},[36,843,844],{"class":514},"        for",[36,846,847],{"class":50}," (",[36,849,504],{"class":42},[36,851,852],{"class":507}," i",[36,854,855],{"class":42}," of",[36,857,744],{"class":117},[36,859,775],{"class":50},[36,861,515],{"class":514},[36,863,518],{"class":117},[36,865,521],{"class":50},[36,867,685],{"class":64},[36,869,114],{"class":50},[36,871,872],{"class":117},"i",[36,874,521],{"class":50},[36,876,118],{"class":117},[36,878,532],{"class":50},[36,880,881],{"class":38,"line":160},[36,882,883],{"class":50},"    },\n",[36,885,886,889,892],{"class":38,"line":166},[36,887,888],{"class":117},"    description:",[36,890,891],{"class":395}," \"Shut down every instance\"",[36,893,894],{"class":50},",\n",[36,896,897],{"class":38,"line":195},[36,898,899],{"class":50},"})\n",[13,901,902,905],{},[33,903,904],{},"list()"," is spawn order and stable — a list you navigate must not reorder under the\ncursor.",[491,907,908],{"id":908},"interrupt",[26,910,912],{"className":28,"code":911,"language":30,"meta":31,"style":31},"keys.register(\"ctrl+alt+x\", () => {\n    if (!agents.interrupt()) tui.warn(\"nothing to interrupt\")\n})\n",[33,913,914,936,967],{"__ignoreMap":31},[36,915,916,919,921,923,925,928,931,934],{"class":38,"line":39},[36,917,918],{"class":117},"keys",[36,920,521],{"class":50},[36,922,717],{"class":64},[36,924,114],{"class":50},[36,926,927],{"class":395},"\"ctrl+alt+x\"",[36,929,930],{"class":50},", () ",[36,932,933],{"class":42},"=>",[36,935,51],{"class":50},[36,937,938,941,943,945,947,949,952,955,957,960,962,965],{"class":38,"line":54},[36,939,940],{"class":514},"    if",[36,942,764],{"class":50},[36,944,5],{"class":117},[36,946,521],{"class":50},[36,948,908],{"class":64},[36,950,951],{"class":50},"()) ",[36,953,954],{"class":117},"tui",[36,956,521],{"class":50},[36,958,959],{"class":64},"warn",[36,961,114],{"class":50},[36,963,964],{"class":395},"\"nothing to interrupt\"",[36,966,532],{"class":50},[36,968,969],{"class":38,"line":61},[36,970,899],{"class":50},[13,972,973,974,977],{},"Stops the focused instance's current wake, as ",[33,975,976],{},"Escape"," does. Interrupted is a settled\noutcome, not an error — nothing is lost from the conversation.",[491,979,981],{"id":980},"an-id-is-not-a-guarantee","An id is not a guarantee",[26,983,985],{"className":28,"code":984,"language":30,"meta":31,"style":31},"if (!agents.get(savedId)) return   \u002F\u002F it may have stopped on its own\nagents.focus(savedId)\n",[33,986,987,1013],{"__ignoreMap":31},[36,988,989,992,994,996,998,1001,1003,1006,1008,1010],{"class":38,"line":39},[36,990,991],{"class":514},"if",[36,993,764],{"class":50},[36,995,5],{"class":117},[36,997,521],{"class":50},[36,999,1000],{"class":64},"get",[36,1002,114],{"class":50},[36,1004,1005],{"class":117},"savedId",[36,1007,832],{"class":50},[36,1009,778],{"class":514},[36,1011,1012],{"class":57},"   \u002F\u002F it may have stopped on its own\n",[36,1014,1015,1017,1019,1021,1023,1025],{"class":38,"line":54},[36,1016,5],{"class":117},[36,1018,521],{"class":50},[36,1020,541],{"class":64},[36,1022,114],{"class":50},[36,1024,1005],{"class":117},[36,1026,532],{"class":50},[1028,1029,1030],"style",{},"html pre.shiki code .scz_3, html code.shiki .scz_3{--shiki-default:#569CD6}html pre.shiki code .sNl3T, html code.shiki .sNl3T{--shiki-default:#4EC9B0}html pre.shiki code .sTNBD, html code.shiki .sTNBD{--shiki-default:#D4D4D4}html pre.shiki code .sOLPB, html code.shiki .sOLPB{--shiki-default:#6A9955}html pre.shiki code .sCudf, html code.shiki .sCudf{--shiki-default:#DCDCAA}html pre.shiki code .s3F5K, html code.shiki .s3F5K{--shiki-default:#9CDCFE}html pre.shiki code .sKc5r, html code.shiki .sKc5r{--shiki-default:#CE9178}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html pre.shiki code .s9McN, html code.shiki .s9McN{--shiki-default:#4FC1FF}html pre.shiki code .sYbnZ, html code.shiki .sYbnZ{--shiki-default:#C586C0}",{"title":31,"searchDepth":54,"depth":54,"links":1032},[1033,1034,1035,1036,1037,1038],{"id":493,"depth":54,"text":494},{"id":595,"depth":54,"text":596},{"id":648,"depth":54,"text":649},{"id":701,"depth":54,"text":702},{"id":908,"depth":54,"text":908},{"id":980,"depth":54,"text":981},"Running instances. You start by name and then address by instance — one agent can\nhave many live instances, so a verb taking a name has no answer for \"which one\".","md",{},"\u002Fdocs\u002Fv2\u002Ftui\u002Fapi\u002Fagents",{"title":5,"description":1039},"docs\u002Fv2\u002Ftui\u002Fapi\u002Fagents","gs4x3hLvDyhP5z9nmlrmxVl55KVhcDUcRMcXxsX9GVA",1786791207939]