Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 04:45 UTC
| 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 | }; |