@soverius-ai/browser-models-agui 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 soverius-ai contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,21 @@
1
- # Temporary Holding Version
1
+ # @soverius-ai/browser-models-agui
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ An [AG-UI](https://docs.ag-ui.com) agent on the engines of `@soverius-ai/browser-models`. CopilotKit or any AG-UI client works unchanged.
4
+
5
+ ```bash
6
+ pnpm add @soverius-ai/browser-models @soverius-ai/browser-models-agui
7
+ ```
8
+
9
+ ```ts
10
+ import { BrowserModelsAgent } from '@soverius-ai/browser-models-agui';
11
+ import { PromptApiEngine } from '@soverius-ai/browser-models/prompt-api';
12
+
13
+ const agent = new BrowserModelsAgent({
14
+ models: { nano: new PromptApiEngine() },
15
+ defaultModel: 'nano',
16
+ });
17
+ ```
18
+
19
+ Chat only: add `@soverius-ai/browser-models-tools` for tool calls. Long conversations are compacted to fit the context (`SummaryCompaction`, or your own `Compaction`).
20
+
21
+ [Docs](https://browser-models.soverius.ai/docs) · [Playground](https://browser-models.soverius.ai/playground) · by [Soverius AI](https://soverius.ai) · MIT
package/agent.d.ts ADDED
@@ -0,0 +1,61 @@
1
+ import { AbstractAgent, type BaseEvent, type RunAgentInput } from '@ag-ui/client';
2
+ import { type Engine } from '@soverius-ai/browser-models';
3
+ import type { Compaction } from './lib/compaction.ts';
4
+ import type { Tools } from './lib/tools.ts';
5
+ /** Options of `BrowserModelsAgent`. */
6
+ export interface BrowserModelsAgentOptions<Engines extends Readonly<Record<string, Engine>>> {
7
+ /** The models this agent may use, by id. Selection is always explicit. */
8
+ readonly models: Engines;
9
+ /** Model used when a run does not pick one. Must be one of the `models` keys. */
10
+ readonly defaultModel: keyof Engines & string;
11
+ readonly agentId?: string;
12
+ readonly description?: string;
13
+ /**
14
+ * Tool calling: `new ToolCalling({ localTools })` of `@soverius-ai/browser-models-tools`.
15
+ * Without it the agent only chats and the client's tools are not offered to the model.
16
+ */
17
+ readonly tools?: Tools;
18
+ /**
19
+ * Keeps long conversations within the model's context. Default `new SummaryCompaction()`:
20
+ * older turns become a summary, old tool results are cut, for engines that report a
21
+ * `contextWindowSize`. Pass your own `Compaction` for another algorithm, or `false` for none.
22
+ */
23
+ readonly compaction?: Compaction | false;
24
+ }
25
+ /**
26
+ * An AG-UI agent backed by a model running in the browser. Works with any AG-UI
27
+ * client, for example CopilotKit: `provideCopilotKit({ agents: { default: agent } })`.
28
+ * Model ids are checked by TypeScript.
29
+ *
30
+ * A run can pick a model with `forwardedProps: { soverius: { model: 'id' } }`.
31
+ * An unknown id fails the run; there is no automatic fallback.
32
+ */
33
+ export declare class BrowserModelsAgent<Engines extends Readonly<Record<string, Engine>> = Readonly<Record<string, Engine>>> extends AbstractAgent {
34
+ private options;
35
+ private models;
36
+ private compaction;
37
+ private abortController;
38
+ constructor(options: BrowserModelsAgentOptions<Engines>);
39
+ /** The model runs use unless a run picks one. Starts as `defaultModel`. */
40
+ get selectedModel(): keyof Engines & string;
41
+ /** Switches the model for the next runs. Only registered ids are accepted. */
42
+ selectModel(modelId: keyof Engines & string): void;
43
+ /** The ids of the registered models. */
44
+ get modelIds(): readonly (keyof Engines & string)[];
45
+ /** The engine for a model id (default: the selected model), for availability or downloads. */
46
+ engine<Id extends keyof Engines & string>(modelId?: Id): Engines[Id];
47
+ /** A copy for a client like CopilotKit. It shares models, selection, tools and compaction. */
48
+ clone(): BrowserModelsAgent<Engines>;
49
+ /** Stops the running model and tools, like `HttpAgent.abortRun()`. Clients call it on "stop". */
50
+ abortRun(): void;
51
+ /** Sends every event of this agent to the soverius debugger. Returns a function that stops it. */
52
+ connectDevtools(target?: Window | undefined): () => void;
53
+ /** Runs the agent on the selected model, or the one `forwardedProps.soverius.model` picks. */
54
+ run(input: RunAgentInput): ReturnType<AbstractAgent['run']>;
55
+ }
56
+ /** Message format the soverius debugger listens for on `window`. */
57
+ export interface DevtoolsMessage {
58
+ readonly source: 'soverius-ai/devtools';
59
+ readonly agentId: string;
60
+ readonly event: BaseEvent;
61
+ }
package/index.d.ts ADDED
@@ -0,0 +1,12 @@
1
+ /**
2
+ * `@soverius-ai/browser-models-agui`: an AG-UI agent on the engines, for CopilotKit or any AG-UI client.
3
+ *
4
+ * @packageDocumentation
5
+ */
6
+ export { BrowserModelsAgent, type BrowserModelsAgentOptions, type DevtoolsMessage, } from './agent.ts';
7
+ export type { Compaction, CompactionRequest, CompactionStatus, LastCall, } from './lib/compaction.ts';
8
+ export { AgentEvents, MODEL_ACTIVITY, type CustomEvents, type ModelActivity, type ToolRepair, type ToolSourceError, } from './lib/events.ts';
9
+ export { buildChatMessages, type PromptMessage } from './lib/prompt.ts';
10
+ export { AgentRun, type RunOptions } from './lib/run.ts';
11
+ export { SummaryCompaction, type SummaryCompactionOptions, } from './lib/summary-compaction.ts';
12
+ export type { CheckedCall, RepairStep, RunTools, ToolCall, Tools, ToolSpec, ToolsRun, } from './lib/tools.ts';
package/index.js ADDED
@@ -0,0 +1,28 @@
1
+ import{AbstractAgent as Ce}from"@ag-ui/client";import{EventType as te}from"@ag-ui/core";var w=class{#e=[];#t=!1;#n;#o;push(e){this.#e.push(e),this.#o?.()}close(){this.#t=!0,this.#o?.()}fail(e){this.#n=e??new Error("Failed."),this.close()}async*[Symbol.asyncIterator](){for(;;){let e=this.#e.shift();if(e!==void 0){yield e;continue}if(this.#n)throw this.#n;if(this.#t)return;await new Promise(n=>this.#o=n),this.#o=void 0}}};var K=[{kind:"tool-call",open:"```tool_call",close:"```"},{kind:"tool-result",open:"```tool_result",close:"```"},{kind:"tool-call",open:"<tool_call>",close:"</tool_call>"},{kind:"reasoning",open:"<think>",close:"</think>"}],M=class{#e="";#t;push(e){this.#e+=e;let n=[];for(;;){let t=this.#t;if(t){let s=this.#e.indexOf(t.close);if(t.kind==="tool-call"){if(s===-1){let a=this.#e.length-_(this.#e,[t.close]),l=this.#e.slice(0,a).trim();return l&&n.push({kind:"tool-call-partial",raw:l}),n}n.push({kind:"tool-call",raw:this.#e.slice(0,s).trim()})}else if(t.kind==="tool-result"){if(s===-1)return this.#e=this.#e.slice(this.#e.length-_(this.#e,[t.close])),n}else{let a=s===-1?this.#e.length-_(this.#e,[t.close]):s;if(S(n,"reasoning",this.#e.slice(0,a)),s===-1)return this.#e=this.#e.slice(a),n;n.push({kind:"reasoning-end"})}this.#e=this.#e.slice(s+t.close.length),this.#t=void 0;continue}let o=this.#n();if(o){S(n,"text",this.#e.slice(0,o.index)),this.#e=this.#e.slice(o.index+o.block.open.length),this.#t=o.block;continue}let i=_(this.#e,K.map(s=>s.open));return S(n,"text",this.#e.slice(0,this.#e.length-i)),this.#e=this.#e.slice(this.#e.length-i),n}}end(){let e=[];return this.#t?.kind==="tool-call"?e.push({kind:"tool-call-cut",raw:this.#e.trim()}):this.#t?.kind==="reasoning"?(S(e,"reasoning",this.#e),e.push({kind:"reasoning-end"})):this.#t?.kind==="tool-result"||S(e,"text",this.#e),this.#e="",this.#t=void 0,e}#n(){let e;for(let n of K){let t=this.#e.indexOf(n.open);t!==-1&&(!e||t<e.index)&&(e={index:t,block:n})}return e}};function S(r,e,n){n&&r.push({kind:e,text:n})}function _(r,e){let n=0;for(let t of e)for(let o=Math.min(t.length-1,r.length);o>n;o--)if(r.endsWith(t.slice(0,o))){n=o;break}return n}var R=class{#e;#t;constructor(e,n){if(!(n in e))throw new Error(`defaultModel "${n}" is not one of the registered models.`);this.#e=e,this.#t=n}get modelIds(){return Object.keys(this.#e)}get selectedModel(){return this.#t}selectModel(e){if(!this.has(e))throw new Error(`Unknown model "${e}".`);this.#t=e}has(e){return Object.hasOwn(this.#e,e)}engine(e=this.#t){if(!this.has(e))throw new Error(`Unknown model "${e}".`);return this.#e[e]}};import{Observable as we}from"rxjs";import{EventType as c}from"@ag-ui/core";import{EventType as V}from"@ag-ui/core";var v="soverius.model",B=class r{static compaction(e){return r.custom(e,"soverius.compaction")}static toolRepair(e){return r.custom(e,"soverius.tool_repair")}static toolSourceError(e){return r.custom(e,"soverius.tool_source_error")}static modelActivity(e){let n=e;return n.type===V.ACTIVITY_SNAPSHOT&&n.activityType===v?n.content:void 0}static custom(e,n){let t=e;return t.type===V.CUSTOM&&t.name===n?t.value:void 0}};function D(r,e,n){let t=[],o=[],i=new Map;for(let s of r)switch(s.role){case"system":case"developer":t.push(s.content);break;case"user":o.push({role:"user",content:b(s.content),source:s});break;case"assistant":{let a=(s.toolCalls??[]).map(d=>(i.set(d.id,d.function.name),G(d.function.name,d.function.arguments))),l=[s.content??"",...a].filter(Boolean).join(`
2
+ `);l&&o.push({role:"assistant",content:l,source:s});break}case"tool":o.push({role:"user",content:I(i.get(s.toolCallId)??"unknown",s.error??(b(s.content)||oe)),source:s});break;default:break}for(let s of e)t.push(`${s.description}:
3
+ ${s.value}`);return n&&t.push(n),t.length>0?[{role:"system",content:t.join(`
4
+
5
+ `)},...o]:o}var oe="Done. The tool ran and returned no data.";function G(r,e){return`\`\`\`tool_call
6
+ {"name": ${JSON.stringify(r)}, "arguments": ${e||"{}"}}
7
+ \`\`\``}function I(r,e){return"```tool_result\n"+JSON.stringify({name:r,result:e})+"\n```"}var se=/```tool_result\n(.*)\n```/g,X=`
8
+ \u2026 (shortened)`;function J(r,e){return r.replace(se,(n,t)=>{let o,i;try{({name:o,result:i}=JSON.parse(t))}catch{return n}return typeof o!="string"||typeof i!="string"||i.length<=e+X.length?n:I(o,i.slice(0,e)+X)})}function b(r){return typeof r=="string"?r:r.map(e=>e.type==="text"?e.text??"":"").join("")}var re="The tool call was cut off before it was complete. Send the whole call again.",x=class{#e;#t;#n=[];#o=new Set;#s;constructor(e){this.#e=e,this.#t=e.signal??new AbortController().signal}async*events(){let{threadId:e,runId:n}=this.#e.input;yield{type:c.RUN_STARTED,threadId:e,runId:n};try{yield*this.#i(),yield{type:c.RUN_FINISHED,threadId:e,runId:n}}catch(t){this.#o.size>0&&(yield this.#r());for(let o of this.#o)yield{type:c.TOOL_CALL_END,toolCallId:o.id};if(this.#t.aborted)yield{type:c.RUN_ERROR,message:"The run was stopped.",code:"abort"};else{let o=t instanceof Error?t.message:String(t);yield{type:c.RUN_ERROR,message:o}}}}async*#i(){let{engine:e,input:n}=this.#e,t=this.#t,o=await this.#e.tools?.start({input:n,engine:e,signal:t});for(let s of o?.errors??[])yield Y("soverius.tool_source_error",{message:s});let i=D(n.messages,n.context,o?.instructions);yield*this.#l(),t.throwIfAborted();for(let s=0;s<(o?.maxSteps??1);s++){let a=yield*this.#a(i),l=new $(o,this.#o),{message:d}=l;this.#n.push(d);let g=new M,u;for await(let p of e.generate({messages:a,signal:t}))p.type==="text"?yield*l.events(g.push(p.text)):u=p.usage;if(t.throwIfAborted(),yield*l.events(g.end()),d.content&&(yield{type:c.TEXT_MESSAGE_END,messageId:d.id}),this.#s=u&&{tokens:u.totalTokens,characters:ie(a)+l.written.length},!o||l.calls.length===0)return;let E=d.content?[d.content]:[],f=[],h=!1;for(let{raw:p,streamed:m,cut:A}of l.calls){t.throwIfAborted();let k=A?{ok:!1,error:re}:await o.check(p,a);if(t.throwIfAborted(),!k.ok){m&&(yield this.#r(),yield{type:c.TOOL_CALL_END,toolCallId:m.id},this.#o.delete(m)),E.push("```tool_call\n"+p+"\n```"),f.push(I("error",k.error));continue}let{call:y,steps:C}=k,T=m?.id??crypto.randomUUID(),N=JSON.stringify(y.arguments);d.toolCalls.push({id:T,type:"function",function:{name:y.name,arguments:N}}),C.length>0&&(yield Y("soverius.tool_repair",{toolCallId:T,raw:p,steps:C})),m||(yield{type:c.TOOL_CALL_START,toolCallId:T,toolCallName:y.name,parentMessageId:d.id});let P=q(N,m?.sent??"");m&&(m.name!==y.name||P===void 0)?yield this.#r():P&&(yield{type:c.TOOL_CALL_ARGS,toolCallId:T,delta:P}),yield{type:c.TOOL_CALL_END,toolCallId:T},m&&this.#o.delete(m),E.push(G(y.name,N)),t.throwIfAborted();let H=o.run(y);if(!H){h=!0;continue}let L=await H,z=crypto.randomUUID();this.#n.push({id:z,role:"tool",toolCallId:T,content:L}),yield{type:c.TOOL_CALL_RESULT,messageId:z,toolCallId:T,content:L,role:"tool"},f.push(I(y.name,L))}if(h)return;i.push({role:"assistant",content:E.join(`
9
+ `)},{role:"user",content:f.join(`
10
+ `)})}}async*#a(e){let{compaction:n,engine:t,input:o}=this.#e;if(!n)return e.map(W);let i=new w,s=n.compact({threadId:o.threadId,messages:e,engine:t,signal:this.#t,report:a=>i.push(a),...this.#s?{lastCall:this.#s}:{}});s.then(()=>i.close(),a=>i.fail(a));for await(let a of i)yield Y("soverius.compaction",a);return(await s).map(W)}#r(){return{type:c.MESSAGES_SNAPSHOT,messages:structuredClone([...this.#e.input.messages.filter(e=>e.role!=="activity"&&e.role!=="reasoning"),...this.#n.filter(e=>e.role!=="assistant"||e.content||e.toolCalls?.length)])}}async*#l(){let{engine:e}=this.#e,n=crypto.randomUUID(),t=new w;e.load({signal:this.#t,onProgress:s=>t.push(s)}).then(()=>t.close(),s=>t.fail(s));let o=!1,i=-1;for await(let s of t){let a=Math.floor(s*100);a!==i&&(i=a,o=!0,yield{type:c.ACTIVITY_SNAPSHOT,messageId:n,activityType:v,content:{engineId:e.id,status:"loading",progress:s}})}o&&(yield{type:c.ACTIVITY_SNAPSHOT,messageId:n,activityType:v,content:{engineId:e.id,status:"ready",progress:1}})}},$=class{message={id:crypto.randomUUID(),role:"assistant",content:"",toolCalls:[]};calls=[];written="";#e;#t;#n;#o;constructor(e,n){this.#e=e,this.#t=n}*events(e){let n=this.message.id;for(let t of e)switch((t.kind==="tool-call"||t.kind==="tool-call-cut")&&(this.written+=t.raw),(t.kind==="text"||t.kind==="reasoning")&&(this.written+=t.text),t.kind){case"tool-call-partial":yield*this.#s(t.raw);break;case"tool-call":case"tool-call-cut":if(!this.#e)break;this.calls.push({raw:t.raw,streamed:this.#n,cut:t.kind==="tool-call-cut"}),this.#n=void 0;break;case"reasoning":if(!this.#o&&!t.text.trim())break;this.#o||(this.#o=crypto.randomUUID(),yield{type:c.REASONING_START,messageId:this.#o},yield{type:c.REASONING_MESSAGE_START,messageId:this.#o,role:"reasoning"}),yield{type:c.REASONING_MESSAGE_CONTENT,messageId:this.#o,delta:t.text};break;case"reasoning-end":this.#o&&(yield{type:c.REASONING_MESSAGE_END,messageId:this.#o},yield{type:c.REASONING_END,messageId:this.#o},this.#o=void 0);break;case"text":{let o=this.message.content?t.text:t.text.trimStart();if(!o)break;this.message.content||(yield{type:c.TEXT_MESSAGE_START,messageId:n,role:"assistant"}),this.message.content+=o,yield{type:c.TEXT_MESSAGE_CONTENT,messageId:n,delta:o};break}}}*#s(e){let n=this.#e?.readPartial(e);if(!n)return;this.#n||(this.#n={id:crypto.randomUUID(),name:n.name,sent:""},this.#t.add(this.#n),yield{type:c.TOOL_CALL_START,toolCallId:this.#n.id,toolCallName:this.#n.name,parentMessageId:this.message.id});let t=q(n.argumentsJson,this.#n.sent);t&&(this.#n.sent+=t,yield{type:c.TOOL_CALL_ARGS,toolCallId:this.#n.id,delta:t})}};function Y(r,e){return{type:c.CUSTOM,name:r,value:e}}function ie(r){return r.reduce((e,n)=>e+n.content.length,0)}function W({role:r,content:e}){return{role:r,content:e}}function q(r,e){return r.startsWith(e)?r.slice(e.length):void 0}var ae=100,le=64,ce=1,de=8,ue=.08,pe=600,me=.05,ge=.025,he=.05,Q="You summarize conversations. Do not continue the conversation and do not answer its questions. Write only the summary.",fe=["Goal: what the user wants","Facts: names, numbers, decisions and what tools returned",'Open: what is still to do, or "nothing"'].join(`
11
+ `),ye="Summarize the conversation above so that another assistant can continue it.",Ee="The conversation above is new. Update the previous summary with it: keep what is still true and add what is new.",Te=`The conversation before this point was compacted into this summary:
12
+ <summary>
13
+ `,Me=`
14
+ </summary>`,O=class{#e;#t;#n;#o;#s=new U;#i=new U;constructor(e={}){this.#e=e.threshold??.9,this.#t=e.keepRecent??.25,this.#n=e.summarize??!0,this.#o=e.charactersPerToken??3}async compact(e){let{engine:n,messages:t,threadId:o,report:i}=e,s=n.contextWindowSize;if(!s||s<0)return t;let a=s*this.#e,l=new j(this.#r(o,e.lastCall)),{from:d,summary:g}=this.#a(o,t),u=Z(t,d,g),E=l.of(u);if(E<=a)return u;let f=this.#c(t,d,this.#l(u,a,s,l),l),h=t.slice(d,f),p=t[f]?.source?.id,m=0,A=0;if(p&&h.length>0){let y=l.of(h)>=s*he,C;this.#n&&y&&(i({status:"summarizing",tokens:E,contextWindowSize:s}),C=await this.#d(h,g,e,s,l)),(y||!this.#n)&&(d=f,g=C??g,this.#s.set(o,{firstKeptId:p,summary:g}),u=Z(t,d,g),C?m=h.length:A=h.length)}let k=this.#u(u,a,Math.floor(s*ge*l.perToken),l);return m+A+k>0&&i({status:"done",tokensBefore:E,tokensAfter:l.of(u),contextWindowSize:s,summarized:m,shortened:k,dropped:A}),u}#a(e,n){let t=this.#s.get(e),o=t?n.findIndex(i=>i.source?.id===t.firstKeptId):-1;return!t||o<0?{from:n[0]?.role==="system"?1:0,summary:void 0}:{from:o,summary:t.summary}}#r(e,n){if(n&&n.tokens>=le){let t=n.characters/n.tokens;this.#i.set(e,Math.min(de,Math.max(ce,t)))}return this.#i.get(e)??this.#o}#l(e,n,t,o){let[i]=e,s=i?.role==="system"?o.of([i]):0,a=n-s-ee(t);return Math.max(0,Math.min(t*this.#t,a/2))}#c(e,n,t,o){let i=e.map(a=>a.source?.role==="user"),s=0;for(let a=e.length-1;a>=n;a--){if(s+=o.of(e.slice(a,a+1)),s<t)continue;let l=i.indexOf(!0,a);return l>=0?l:Math.max(n,i.lastIndexOf(!0))}return n}async#d(e,n,{engine:t,signal:o},i,s){let a=i*s.perToken,l=Math.floor(ee(i)*s.perToken),d=Math.max(30,Math.floor(l/70)*10),g=[...n?[`<previous-summary>
15
+ ${n}
16
+ </previous-summary>`]:[],`${n?Ee:ye} Use at most ${d} words and this format:`,fe].join(`
17
+
18
+ `),u=ke(e.flatMap(p=>p.source??[]),Math.floor(a*me)),E=a-l-g.length-Q.length;for(;u.length>1&&u.join(`
19
+
20
+ `).length>E;)u.shift();let f=new M,h="";try{for await(let p of t.generate({messages:[{role:"system",content:Q},{role:"user",content:`<conversation>
21
+ ${u.join(`
22
+
23
+ `)}
24
+ </conversation>
25
+
26
+ ${g}`}],signal:o}))if(p.type==="text")for(let m of f.push(p.text))m.kind==="text"&&(h+=m.text);for(let p of f.end())p.kind==="text"&&(h+=p.text)}catch(p){if(o.aborted)throw p;return}return o.throwIfAborted(),h.trim().slice(0,l)||void 0}#u(e,n,t,o){let i=0;for(let[s,a]of e.entries()){let l=o.of(e)-n;if(l<=0)break;let d=s===e.length-1?(o.of([a])-l)*o.perToken:0,g=a.content;for(let u=d;g=J(a.content,Math.max(t,u)),e[s]={...a,content:g},!(u<=t||o.of(e)<=n);u=Math.floor(u*.8));g!==a.content&&i++}return i}};function Z(r,e,n){let[t]=r,o=[t?.role==="system"?t.content:"",n?Te+n+Me:""].filter(Boolean).join(`
27
+
28
+ `);return[...o?[{role:"system",content:o}]:[],...r.slice(e)]}function ee(r){return Math.min(pe,r*ue)}function ke(r,e){let n=[],t=(o,i)=>{i&&n.push(`[${o}]: ${i.slice(0,e)}`)};for(let o of r)if(o.role==="user"&&t("User",b(o.content)),o.role==="tool"&&t("Tool result",o.error??b(o.content)),o.role==="assistant"){t("Assistant",o.content??"");for(let i of o.toolCalls??[])t("Assistant tool call",`${i.function.name}(${i.function.arguments})`)}return n}var j=class{perToken;constructor(e){this.perToken=e}of(e){return e.reduce((n,t)=>n+Math.ceil(t.content.length/this.perToken)+4,0)}},U=class{#e=new Map;get(e){return this.#e.get(e)}set(e,n){this.#e.delete(e),this.#e.set(e,n);let t=this.#e.keys().next().value;this.#e.size>ae&&t!==void 0&&this.#e.delete(t)}};var F=class extends Ce{options;models;compaction;abortController;constructor(e){super({...e.agentId?{agentId:e.agentId}:{},description:e.description??"An agent running on a model in the browser"}),this.options=e,this.models=new R(e.models,e.defaultModel),this.compaction=e.compaction===!1?void 0:e.compaction??new O}get selectedModel(){return this.models.selectedModel}selectModel(e){this.models.selectModel(e)}get modelIds(){return this.models.modelIds}engine(e=this.models.selectedModel){return this.models.engine(e)}clone(){let e=super.clone();return e.options=this.options,e.models=this.models,e.compaction=this.compaction,e}abortRun(){this.abortController?.abort(),super.abortRun()}connectDevtools(e=globalThis.window){if(!e)return()=>{};let{unsubscribe:n}=this.subscribe({onEvent:({event:t})=>{let o={source:"soverius-ai/devtools",agentId:this.agentId??"default",event:t};e.postMessage(o,"/")}});return n}run(e){return new we(n=>{let t=new AbortController;this.abortController=t;let o=Ae(e)??this.models.selectedModel,i=this.models.has(o)?new x({engine:this.models.engine(o),input:e,signal:t.signal,...this.options.tools?{tools:this.options.tools}:{},...this.compaction?{compaction:this.compaction}:{}}).events():Se(e,o);return(async()=>{for await(let s of i)n.next(s);n.complete()})().catch(s=>n.error(s)),()=>t.abort()})}};function Ae(r){let e=r.forwardedProps,n=ne(e)?e.soverius:void 0,t=ne(n)?n.model:void 0;return typeof t=="string"?t:void 0}function ne(r){return typeof r=="object"&&r!==null}async function*Se(r,e){yield{type:te.RUN_STARTED,threadId:r.threadId,runId:r.runId},yield{type:te.RUN_ERROR,message:`Unknown model "${e}".`}}export{B as AgentEvents,x as AgentRun,F as BrowserModelsAgent,v as MODEL_ACTIVITY,O as SummaryCompaction,D as buildChatMessages};
@@ -0,0 +1,62 @@
1
+ import type { ChatMessage, Engine } from '@soverius-ai/browser-models';
2
+ import type { PromptMessage } from './prompt.ts';
3
+ /**
4
+ * Keeps a conversation within the model's context. The agent uses `SummaryCompaction` unless
5
+ * it gets another one: implement this interface for an algorithm of your own.
6
+ */
7
+ export interface Compaction {
8
+ /**
9
+ * Called before every model call. Returns the messages the model gets: `request.messages`
10
+ * as they are, or fewer, shorter or other ones. An error fails the run.
11
+ *
12
+ * Every call gets the whole conversation again, also what an earlier call left out. Keep
13
+ * what is expensive to make, for example a summary, by `threadId`.
14
+ */
15
+ compact(request: CompactionRequest): Promise<readonly ChatMessage[]>;
16
+ }
17
+ /** What `Compaction.compact()` gets before every model call. */
18
+ export interface CompactionRequest {
19
+ readonly threadId: string;
20
+ /**
21
+ * What the model would get. First the system prompt, if there is one: the instructions and
22
+ * the tool descriptions. Then the whole conversation, each message with its AG-UI `source`.
23
+ * Last the tool calls and results the run has added so far, without a `source`.
24
+ */
25
+ readonly messages: readonly PromptMessage[];
26
+ /** The model of the run: for its `contextWindowSize`, or to write a summary with. */
27
+ readonly engine: Engine;
28
+ /** Aborts when the run is stopped. */
29
+ readonly signal: AbortSignal;
30
+ /** Sends the CUSTOM event `soverius.compaction` with this value to the client. */
31
+ readonly report: (status: CompactionStatus) => void;
32
+ /**
33
+ * The last model call of this run, when the engine counted its tokens: a real measure of
34
+ * how many characters make a token for this model and language.
35
+ */
36
+ readonly lastCall?: LastCall;
37
+ }
38
+ /** A model call and the tokens the engine counted for it. */
39
+ export interface LastCall {
40
+ /** Prompt and reply together, counted by the engine. */
41
+ readonly tokens: number;
42
+ /** The characters of the prompt's messages and of the reply. */
43
+ readonly characters: number;
44
+ }
45
+ /** Value of the CUSTOM event `soverius.compaction`. Token counts are estimates. */
46
+ export type CompactionStatus = {
47
+ /** The model is writing a summary: the answer starts after it. */
48
+ readonly status: 'summarizing';
49
+ readonly tokens: number;
50
+ readonly contextWindowSize: number;
51
+ } | {
52
+ readonly status: 'done';
53
+ readonly tokensBefore: number;
54
+ readonly tokensAfter: number;
55
+ readonly contextWindowSize: number;
56
+ /** Messages a new summary stands for. */
57
+ readonly summarized: number;
58
+ /** Messages whose tool results were cut. */
59
+ readonly shortened: number;
60
+ /** Messages left out without a summary. */
61
+ readonly dropped: number;
62
+ };
@@ -0,0 +1,54 @@
1
+ import { type BaseEvent } from '@ag-ui/core';
2
+ import type { CompactionStatus } from './compaction.ts';
3
+ import type { RepairStep } from './tools.ts';
4
+ /** `activityType` of the model loading events. */
5
+ export declare const MODEL_ACTIVITY = "soverius.model";
6
+ /** Content of the `soverius.model` activity: the model loads before the first answer. */
7
+ export interface ModelActivity {
8
+ readonly engineId: string;
9
+ readonly status: 'loading' | 'ready';
10
+ /** From 0 to 1. */
11
+ readonly progress: number;
12
+ }
13
+ /** Value of `soverius.tool_repair`: a tool call the agent had to fix. */
14
+ export interface ToolRepair {
15
+ readonly toolCallId: string;
16
+ /** What the model wrote. */
17
+ readonly raw: string;
18
+ readonly steps: readonly RepairStep[];
19
+ }
20
+ /** Value of `soverius.tool_source_error`: a tool source failed, the run goes on without it. */
21
+ export interface ToolSourceError {
22
+ readonly message: string;
23
+ }
24
+ /** The value of each `CUSTOM` event the agent sends, by name. */
25
+ export interface CustomEvents {
26
+ readonly 'soverius.compaction': CompactionStatus;
27
+ readonly 'soverius.tool_repair': ToolRepair;
28
+ readonly 'soverius.tool_source_error': ToolSourceError;
29
+ }
30
+ /**
31
+ * Reads the agent's own events, typed, from any AG-UI event. Each method answers undefined for
32
+ * every other event.
33
+ *
34
+ * ```ts
35
+ * agent.subscribe({
36
+ * onEvent: ({ event }) => {
37
+ * const status = AgentEvents.compaction(event);
38
+ * if (status?.status === 'summarizing') showHint('Summarizing the conversation…');
39
+ * },
40
+ * });
41
+ * ```
42
+ */
43
+ export declare class AgentEvents {
44
+ /** The value of `soverius.compaction`. */
45
+ static compaction(event: BaseEvent): CompactionStatus | undefined;
46
+ /** The value of `soverius.tool_repair`. */
47
+ static toolRepair(event: BaseEvent): ToolRepair | undefined;
48
+ /** The value of `soverius.tool_source_error`. */
49
+ static toolSourceError(event: BaseEvent): ToolSourceError | undefined;
50
+ /** The content of a `soverius.model` activity. */
51
+ static modelActivity(event: BaseEvent): ModelActivity | undefined;
52
+ /** The value of a `CUSTOM` event of the agent with this name. */
53
+ static custom<Name extends keyof CustomEvents>(event: BaseEvent, name: Name): CustomEvents[Name] | undefined;
54
+ }
@@ -0,0 +1,29 @@
1
+ import type { Context, Message } from '@ag-ui/core';
2
+ import type { ChatMessage } from '@soverius-ai/browser-models';
3
+ /** A message of the prompt, and the AG-UI message it was made from. */
4
+ export interface PromptMessage extends ChatMessage {
5
+ /**
6
+ * The client's message this one was made from. Not set for the system prompt, and for the
7
+ * tool calls and results a run adds.
8
+ */
9
+ readonly source?: Message;
10
+ }
11
+ /**
12
+ * Turns the AG-UI conversation into plain chat messages. System and developer messages, the
13
+ * context and the tool `instructions` become one system prompt.
14
+ */
15
+ export declare function buildChatMessages(messages: readonly Message[], context: readonly Context[], instructions?: string): PromptMessage[];
16
+ /** How a tool call looks in the conversation the model sees. */
17
+ export declare function toolCallBlock(name: string, argumentsJson: string): string;
18
+ /** How a tool result looks in the conversation the model sees. */
19
+ export declare function toolResultBlock(name: string, result: string): string;
20
+ /**
21
+ * Cuts the results in the `tool_result` blocks of a message to `length` characters, to save
22
+ * context. Everything else stays as it is.
23
+ */
24
+ export declare function shortenToolResults(content: string, length: number): string;
25
+ /** The text of a message whose content may come in parts. */
26
+ export declare function textOf(content: string | readonly {
27
+ type: string;
28
+ text?: string;
29
+ }[]): string;
package/lib/run.d.ts ADDED
@@ -0,0 +1,37 @@
1
+ import { type Event as AgUiEvent, type RunAgentInput } from '@ag-ui/core';
2
+ import { type Engine } from '@soverius-ai/browser-models';
3
+ import type { Compaction } from './compaction.ts';
4
+ import type { Tools } from './tools.ts';
5
+ /** Options of `AgentRun`. */
6
+ export interface RunOptions {
7
+ readonly engine: Engine;
8
+ readonly input: RunAgentInput;
9
+ /** Tool calling. Without it the run only chats: the client's tools are not offered. */
10
+ readonly tools?: Tools;
11
+ /** Keeps the conversation within the model's context. Without it nothing is compacted. */
12
+ readonly compaction?: Compaction;
13
+ readonly signal?: AbortSignal;
14
+ }
15
+ /**
16
+ * One AG-UI run against a browser engine. `events()` yields its AG-UI events.
17
+ *
18
+ * - Text is streamed as TEXT_MESSAGE_* events.
19
+ * - A tool call is streamed while the model writes it: TOOL_CALL_START when the name is
20
+ * known, then TOOL_CALL_ARGS deltas.
21
+ * - Every tool call is checked once it is complete (see `Tools`). AG-UI cannot take
22
+ * back arguments that were sent, so the call stays open until it is repaired. When the
23
+ * repaired call continues what was sent, the rest follows as a delta. If not, a
24
+ * MESSAGES_SNAPSHOT replaces the call (or removes it, when it cannot be repaired). Only then
25
+ * comes TOOL_CALL_END, so at TOOL_CALL_END the client always holds the repaired call.
26
+ * - Tools of the agent run here and the loop continues with their result.
27
+ * - Before every model call the compaction may cut the chat to fit the model's context (see
28
+ * Compaction).
29
+ * - A frontend tool call ends the run: the client runs it and starts a follow-up run.
30
+ * - Without `tools` the run is one model call with text and thinking only.
31
+ */
32
+ export declare class AgentRun {
33
+ #private;
34
+ constructor(options: RunOptions);
35
+ /** Runs the run. Call it once. */
36
+ events(): AsyncGenerator<AgUiEvent>;
37
+ }
@@ -0,0 +1,45 @@
1
+ import { type ChatMessage } from '@soverius-ai/browser-models';
2
+ import type { Compaction, CompactionRequest } from './compaction.ts';
3
+ /** All sizes are shares of the model's context, so they fit a model with 4096 tokens or 128000. */
4
+ export interface SummaryCompactionOptions {
5
+ /**
6
+ * Compact when the prompt fills more than this share of the model's context. The rest is
7
+ * room for the reply. Default 0.9.
8
+ */
9
+ readonly threshold?: number;
10
+ /**
11
+ * How much of the newest conversation stays word for word, as a share of the context. What
12
+ * is older becomes the summary. Default 0.25.
13
+ */
14
+ readonly keepRecent?: number;
15
+ /**
16
+ * Replace older turns with a summary the model writes: one extra model call, and the summary
17
+ * is kept for the next runs of the thread. `false` leaves older turns out without a summary.
18
+ * Default true.
19
+ */
20
+ readonly summarize?: boolean;
21
+ /**
22
+ * Characters per token, to estimate the size of the prompt. Default 3, which is careful for
23
+ * English and code. Use 1 for Chinese, Japanese or Korean.
24
+ */
25
+ readonly charactersPerToken?: number;
26
+ }
27
+ /**
28
+ * The compaction of the pi coding agent, with sizes for small models:
29
+ *
30
+ * 1. The newest turns stay word for word, up to `keepRecent` of the context. The cut is always
31
+ * at a user message, so a turn stays whole and the chat still starts with the user.
32
+ * 2. The turns before the cut become a summary the model writes. The cut and its summary are
33
+ * kept by thread: the next model calls reuse them, and a later compaction updates the
34
+ * summary with the turns since. Without a summary (switched off, or the model failed) those
35
+ * turns are left out.
36
+ * 3. If one turn alone is too large, its tool results are cut, oldest first. pi writes a second
37
+ * summary here; that is one more model call in the middle of a run, too slow in a browser.
38
+ *
39
+ * The current turn is never left out: the model needs the question it answers.
40
+ */
41
+ export declare class SummaryCompaction implements Compaction {
42
+ #private;
43
+ constructor(options?: SummaryCompactionOptions);
44
+ compact(request: CompactionRequest): Promise<readonly ChatMessage[]>;
45
+ }
package/lib/tools.d.ts ADDED
@@ -0,0 +1,64 @@
1
+ import type { RunAgentInput } from '@ag-ui/core';
2
+ import type { ChatMessage, Engine, JsonSchema } from '@soverius-ai/browser-models';
3
+ /** What the model needs to know about a tool. */
4
+ export interface ToolSpec {
5
+ readonly name: string;
6
+ readonly description: string;
7
+ /** JSON Schema of the arguments object. */
8
+ readonly parameters?: JsonSchema;
9
+ }
10
+ /** A tool call after parsing and repair. */
11
+ export interface ToolCall {
12
+ readonly name: string;
13
+ readonly arguments: Readonly<Record<string, unknown>>;
14
+ }
15
+ /** How a broken tool call was fixed, in the order the steps ran. */
16
+ export type RepairStep = 'json' | 'name' | 'coerce' | 'reask' | 'hook';
17
+ /** A finished tool call, checked: a valid call, or what is wrong with it for the model. */
18
+ export type CheckedCall = {
19
+ readonly ok: true;
20
+ readonly call: ToolCall;
21
+ readonly steps: readonly RepairStep[];
22
+ } | {
23
+ readonly ok: false;
24
+ readonly error: string;
25
+ };
26
+ /**
27
+ * Tool calling for the agent. Without it the agent only chats: the client's tools are not
28
+ * offered to the model. `ToolCalling` of `@soverius-ai/browser-models-tools` implements it.
29
+ */
30
+ export interface Tools {
31
+ /** Called at the start of every run, before the model is loaded. */
32
+ start(run: ToolsRun): Promise<RunTools>;
33
+ }
34
+ /** What `Tools.start()` gets at the start of a run. */
35
+ export interface ToolsRun {
36
+ /** `input.tools` are the client's tools: the client runs them. */
37
+ readonly input: RunAgentInput;
38
+ readonly engine: Engine;
39
+ /** Aborts when the run is stopped. */
40
+ readonly signal: AbortSignal;
41
+ }
42
+ /** The tools of one run. */
43
+ export interface RunTools {
44
+ /** Every tool the model may call. */
45
+ readonly tools: readonly ToolSpec[];
46
+ /** How to call them, for the system prompt. */
47
+ readonly instructions: string | undefined;
48
+ /** Problems to report to the client, for example a tool source that could not be read. */
49
+ readonly errors: readonly string[];
50
+ /** Most model calls in the run, counting the ones after tool results. */
51
+ readonly maxSteps: number;
52
+ /** Name and arguments so far of a call the model is still writing, once they can be read. */
53
+ readPartial(raw: string): {
54
+ readonly name: string;
55
+ readonly argumentsJson: string;
56
+ } | undefined;
57
+ /**
58
+ * Parses, repairs and checks a call the model has finished writing. `prompt` is what the
59
+ * model got, so it can be asked again.
60
+ */
61
+ check(raw: string, prompt: readonly ChatMessage[]): Promise<CheckedCall>;
62
+ /** Runs a tool of the agent and returns its result for the model. Undefined: a client tool. */
63
+ run(call: ToolCall): Promise<string> | undefined;
64
+ }
package/package.json CHANGED
@@ -1,6 +1,33 @@
1
1
  {
2
2
  "name": "@soverius-ai/browser-models-agui",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.2.0",
4
+ "type": "module",
5
+ "main": "./index.js",
6
+ "types": "./index.d.ts",
7
+ "sideEffects": false,
8
+ "license": "MIT",
9
+ "homepage": "https://browser-models.soverius.ai",
10
+ "description": "AG-UI agent for @soverius-ai/browser-models: works with CopilotKit and any AG-UI client.",
11
+ "peerDependencies": {
12
+ "@soverius-ai/browser-models": "0.2.0",
13
+ "@ag-ui/client": "^1.0.0",
14
+ "@ag-ui/core": "^1.0.0",
15
+ "rxjs": "^7.8.0"
16
+ },
17
+ "exports": {
18
+ "./package.json": "./package.json",
19
+ ".": {
20
+ "types": "./index.d.ts",
21
+ "import": "./index.js",
22
+ "default": "./index.js"
23
+ }
24
+ },
25
+ "repository": {
26
+ "type": "git",
27
+ "url": "git+https://github.com/Soverius-AI/browser-models.git",
28
+ "directory": "libs/agent/browser-models-agui"
29
+ },
30
+ "publishConfig": {
31
+ "access": "public"
32
+ }
6
33
  }