@amalgm/agents 0.1.3 → 0.2.0

package/docs/DRIVERS.md

@@ -1,72 +0,0 @@
-# Agent drivers
-
-Drivers connect durable Agents state to a native or hosted runtime. They are
-registered by the embedding process and selected by `definition.driver.id`.
-
-```ts
-import { defineDriver } from '@amalgm/agents';
-
-export default defineDriver({
-  id: 'my-runtime',
-  async run(request, context) {
-    context.signal.throwIfAborted();
-    context.emit({ type: 'text.delta', data: { text: 'Working…' } });
-
-    return {
-      driverSessionId: request.driverSessionId ?? 'native-session-id',
-      message: {
-        role: 'assistant',
-        parts: [{ type: 'text', text: 'Done.' }],
-      },
-      metadata: { provider: 'example' },
-    };
-  },
-});
-```
-
-## Request
-
-`DriverRunRequest` includes:
-
-- the immutable `AgentRevision`;
-- the durable session and current turn;
-- ordered completed history before this turn;
-- the accepted input; and
-- the opaque `driverSessionId` returned by an earlier turn.
-
-Drivers do not receive a database handle. They resolve Toolbox actions,
-credentials, skills, files, and native processes through dependencies supplied
-by their host.
-
-## Events and results
-
-Call `context.emit` for streaming or structured observations. The event is
-committed before the call returns. Use type `message` with an assistant
-`AgentMessage` for a durable output message; other event names are driver-owned
-and their data must be JSON.
-
-A final returned `message` is appended once before turn completion. Returned
-`driverSessionId` replaces the prior opaque value for future continuation.
-
-## Cancellation and limits
-
-Drivers must observe `context.signal` and stop their underlying process or
-request. The service records cancellation intent before aborting the signal.
-Input and event sizes are bounded. A driver that emits invalid or oversized
-data fails the turn explicitly.
-
-The in-process boundary cannot forcibly kill an uncooperative driver. Process
-drivers should own their child process and terminate it when signalled.
-
-## Loading drivers in CLIs
-
-Compile driver modules to JavaScript and export either an `AgentDriver`, a
-`driver` value, or a zero-argument factory:
-
-```bash
-AMALGM_AGENT_DRIVERS=./dist/codex-driver.js amalgm-agents-rest
-amalgm-agents --drivers ./dist/codex-driver.js talk reviewer "Review this"
-```
-
-Multiple modules are comma-separated. Secret values belong in the host's
-credential resolver, not in agent definitions or driver module arguments.