Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
ts 142 lines 5.25 KB
Raw
1 /**
2 * A minimal agent: one model, one tool (`shell`), a loop that runs each
3 * command the model asks for and hands back what it printed.
4 *
5 * It exists to drive the CLI the way a coding agent does, so it adds nothing
6 * of its own: no planning prompt, no retries, no command rewriting. The one
7 * other voice is the person the agent works for, who may answer when the model
8 * stops to wait for them.
9 */
10
11 import type { Usage } from './usage';
12
13 export interface ShellCall {
14 /** The provider's id for the tool call. */
15 readonly id: string;
16 readonly command: string;
17 }
18
19 export interface ShellOutcome {
20 readonly exitCode: number;
21 readonly stdout: string;
22 readonly stderr: string;
23 }
24
25 /** Why the loop ended. */
26 export type StopReason =
27 /** The model answered without asking for another command. */
28 | 'finished'
29 /** The turn limit was reached while the model still wanted to run commands. */
30 | 'turn-limit'
31 /** The model stopped for a reason of its own (`max_tokens`, `refusal`, …). */
32 | { readonly provider: string };
33
34 export interface ModelTurn {
35 readonly text: string;
36 readonly calls: ReadonlyArray<ShellCall>;
37 /** Set when the provider reports a stop the loop cannot continue from. */
38 readonly stopped?: string;
39 }
40
41 /** One provider's wire format. It owns the conversation it sends. */
42 export interface ModelAdapter {
43 readonly provider: 'anthropic' | 'openai';
44 readonly model: string;
45 /** Asks the model for its next turn, given everything recorded so far. */
46 next(): Promise<ModelTurn>;
47 /** Records the outcomes of the calls of the turn `next()` just returned. */
48 record(results: ReadonlyArray<{ call: ShellCall; payload: string }>): void;
49 /** Adds a message from the person, after a turn that asked for no command. */
50 say(message: string): void;
51 /** Tokens and cost so far, for an adapter that talks to a real provider. */
52 usage?(): Usage;
53 /**
54 * Whether a turn that asked for no command still leaves turns to play. Only
55 * a scripted path knows that; for a model, such a turn is its last.
56 */
57 hasMore?(): boolean;
58 }
59
60 export interface ExecutedCommand extends ShellOutcome {
61 readonly command: string;
62 /** The exact text the model received for this command. */
63 readonly payload: string;
64 }
65
66 export interface Transcript {
67 readonly commands: ReadonlyArray<ExecutedCommand>;
68 /** The model's text, per turn, in order. */
69 readonly messages: ReadonlyArray<string>;
70 /** What the person answered, and after which model turn. */
71 readonly replies: ReadonlyArray<{ readonly afterModelTurn: number; readonly text: string }>;
72 readonly stop: StopReason;
73 readonly modelTurns: number;
74 }
75
76 export const SHELL_TOOL = {
77 name: 'shell',
78 description:
79 "Run a command line with sh in the user's terminal. Returns the exit code, stdout, and stderr.",
80 parameters: {
81 type: 'object' as const,
82 properties: {
83 command: { type: 'string', description: 'The command line to run.' },
84 },
85 required: ['command'],
86 additionalProperties: false,
87 },
88 };
89
90 /** The tool result as the model reads it. `exit_code` leads so a fixture can gate on it. */
91 export const toolPayload = (outcome: ShellOutcome): string =>
92 JSON.stringify({ exit_code: outcome.exitCode, stdout: outcome.stdout, stderr: outcome.stderr });
93
94 export const runAgent = async (options: {
95 adapter: ModelAdapter;
96 /** Runs a command and returns its output, already scrubbed for the model. */
97 execute: (command: string) => Promise<ShellOutcome>;
98 /**
99 * Hands the person what the model wrote in each turn, which may be nothing.
100 * `waiting` is true when the model asked for no command; a returned string
101 * is their reply, and the loop goes on with it.
102 */
103 hear?: (message: string, waiting: boolean) => string | undefined;
104 /** Hard cap on model turns, so a looping model cannot run forever. */
105 maxTurns: number;
106 }): Promise<Transcript> => {
107 const commands: ExecutedCommand[] = [];
108 const messages: string[] = [];
109 const replies: Array<{ afterModelTurn: number; text: string }> = [];
110
111 for (let turn = 1; turn <= options.maxTurns; turn += 1) {
112 const { text, calls, stopped } = await options.adapter.next();
113 if (text !== '') messages.push(text);
114 if (stopped !== undefined) {
115 return { commands, messages, replies, stop: { provider: stopped }, modelTurns: turn };
116 }
117 const waiting = calls.length === 0;
118 // The person reads the text before the turn's commands run, as they would in a chat.
119 const reply = options.hear?.(text, waiting);
120 if (waiting) {
121 if (reply === undefined) {
122 if (options.adapter.hasMore?.() === true) continue;
123 return { commands, messages, replies, stop: 'finished', modelTurns: turn };
124 }
125 replies.push({ afterModelTurn: turn, text: reply });
126 options.adapter.say(reply);
127 continue;
128 }
129
130 const results: Array<{ call: ShellCall; payload: string }> = [];
131 // One at a time: the commands share a home directory and a backend.
132 for (const call of calls) {
133 const outcome = await options.execute(call.command);
134 const payload = toolPayload(outcome);
135 commands.push({ command: call.command, ...outcome, payload });
136 results.push({ call, payload });
137 }
138 options.adapter.record(results);
139 }
140
141 return { commands, messages, replies, stop: 'turn-limit', modelTurns: options.maxTurns };
142 };