@soederpop/luca 0.0.32 → 0.0.34

package/docs/apis/features/node/ink.md

@@ -32,7 +32,7 @@ container.feature('ink', {
 
 Pre-load ink + react modules so the sync getters work. Called automatically by render(), but you can call it early.
 
-**Returns:** `void`
+**Returns:** `Promise<this>`
 
 ```ts
 const ink = container.feature('ink', { enable: true })
@@ -54,7 +54,7 @@ Mount a React element to the terminal. Wraps `ink.render()` — automatically lo
 | `node` | `any` | ✓ | A React element (JSX or React.createElement) |
 | `options` | `Record<string, any>` |  | Ink render options (stdout, stdin, debug, etc.) |
 
-**Returns:** `void`
+**Returns:** `Promise<any>`
 
 
 
@@ -138,7 +138,7 @@ Register a named React function component as a renderable block.
 | `name` | `string` | ✓ | Unique block name |
 | `component` | `Function` | ✓ | A React function component |
 
-**Returns:** `void`
+**Returns:** `this`
 
 ```ts
 ink.registerBlock('Greeting', ({ name }) =>
@@ -159,7 +159,7 @@ Render a registered block by name with optional props. Looks up the component, c
 | `name` | `string` | ✓ | The registered block name |
 | `data` | `Record<string, any>` |  | Props to pass to the component |
 
-**Returns:** `void`
+**Returns:** `Promise<void>`
 
 ```ts
 await ink.renderBlock('Greeting', { name: 'Jon' })
@@ -179,7 +179,7 @@ Render a registered block that needs to stay mounted for async work. The compone
 | `data` | `Record<string, any>` |  | Props to pass to the component (a `done` prop is added automatically) |
 | `options` | `{ timeout?: number }` |  | `timeout` in ms before force-unmounting (default 30 000) |
 
-**Returns:** `void`
+**Returns:** `Promise<void>`
 
 ```tsx
 // In a ## Blocks section:
@@ -205,12 +205,12 @@ await renderAsync('AsyncChart', { url: 'https://api.example.com/data' })
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `React` | `any` | The React module (createElement, useState, useEffect, etc.) Exposed so consumers don't need a separate react import. Lazy-loaded — first access triggers the import. |
-| `components` | `any` | All Ink components as a single object for destructuring. ```ts const { Box, Text, Static, Spacer } = ink.components ``` |
-| `hooks` | `any` | All Ink hooks as a single object for destructuring. ```ts const { useInput, useApp, useFocus } = ink.hooks ``` |
-| `measureElement` | `any` | The Ink measureElement utility. |
+| `React` | `typeof import('react')` | The React module (createElement, useState, useEffect, etc.) Exposed so consumers don't need a separate react import. Lazy-loaded — first access triggers the import. |
+| `components` | `{ Box: typeof import('ink').Box; Text: typeof import('ink').Text; Static: typeof import('ink').Static; Transform: typeof import('ink').Transform; Newline: typeof import('ink').Newline; Spacer: typeof import('ink').Spacer }` | All Ink components as a single object for destructuring. ```ts const { Box, Text, Static, Spacer } = ink.components ``` |
+| `hooks` | `{ useInput: typeof import('ink').useInput; useApp: typeof import('ink').useApp; useStdin: typeof import('ink').useStdin; useStdout: typeof import('ink').useStdout; useStderr: typeof import('ink').useStderr; useFocus: typeof import('ink').useFocus; useFocusManager: typeof import('ink').useFocusManager; useCursor: typeof import('ink').useCursor }` | All Ink hooks as a single object for destructuring. ```ts const { useInput, useApp, useFocus } = ink.hooks ``` |
+| `measureElement` | `typeof import('ink').measureElement` | The Ink measureElement utility. |
 | `isMounted` | `boolean` | Whether an ink app is currently mounted. |
-| `instance` | `any` | The raw ink render instance if you need low-level access. |
+| `instance` | `any | null` | The raw ink render instance if you need low-level access. |
 | `blocks` | `string[]` | List all registered block names. |
 
 ## Events (Zod v4 schema)

package/docs/apis/features/node/ipc-socket.md

@@ -1,6 +1,6 @@
 # IpcSocket (features.ipcSocket)
 
-IpcSocket Feature - Inter-Process Communication via Unix Domain Sockets This feature provides robust IPC (Inter-Process Communication) capabilities using Unix domain sockets. It supports both server and client modes, allowing processes to communicate efficiently through file system-based socket connections. **Key Features:** - Dual-mode operation: server and client functionality - JSON message serialization/deserialization - Multiple client connection support (server mode) - Event-driven message handling - Automatic socket cleanup and management - Broadcast messaging to all connected clients - Lock file management for socket paths **Communication Pattern:** - Messages are automatically JSON-encoded with unique IDs - Both server and client emit 'message' events for incoming data - Server can broadcast to all connected clients - Client maintains single connection to server **Socket Management:** - Automatic cleanup of stale socket files - Connection tracking and management - Graceful shutdown procedures - Lock file protection against conflicts **Usage Examples:** **Server Mode:** ```typescript const ipc = container.feature('ipcSocket'); await ipc.listen('/tmp/myapp.sock', true); // removeLock=true ipc.on('connection', (socket) => { console.log('Client connected'); }); ipc.on('message', (data) => { console.log('Received:', data); ipc.broadcast({ reply: 'ACK', original: data }); }); ``` **Client Mode:** ```typescript const ipc = container.feature('ipcSocket'); await ipc.connect('/tmp/myapp.sock'); ipc.on('message', (data) => { console.log('Server says:', data); }); await ipc.send({ type: 'request', payload: 'hello' }); ```
+IpcSocket Feature - Inter-Process Communication via Unix Domain Sockets This feature provides robust IPC (Inter-Process Communication) capabilities using Unix domain sockets. It supports both server and client modes, allowing processes to communicate efficiently through file system-based socket connections. **Key Features:** - Hub-and-spoke: one server, many named clients with identity tracking - Targeted messaging: sendTo(clientId), broadcast(msg, excludeId) - Request/reply: ask() + reply() with timeout-based correlation - Auto-reconnect: clients reconnect with exponential backoff - Stale socket detection: probeSocket() before listen() - Clean shutdown: stopServer() removes socket file **Server (Hub):** ```typescript const ipc = container.feature('ipcSocket'); await ipc.listen('/tmp/hub.sock', true); ipc.on('connection', (clientId, socket) => { console.log('Client joined:', clientId); }); ipc.on('message', (data, clientId) => { console.log(`From ${clientId}:`, data); // Reply to sender, or ask and wait ipc.sendTo(clientId, { ack: true }); }); ``` **Client (Spoke):** ```typescript const ipc = container.feature('ipcSocket'); await ipc.connect('/tmp/hub.sock', { reconnect: true, name: 'worker-1' }); // Fire and forget await ipc.send({ type: 'status', ready: true }); // Request/reply ipc.on('message', (data) => { if (data.requestId) ipc.reply(data.requestId, { result: 42 }); }); ```
 
 ## Usage
 
@@ -64,81 +64,113 @@ try {
 
 ### broadcast
 
-Broadcasts a message to all connected clients (server mode only). This method sends a JSON-encoded message with a unique ID to every client currently connected to the server. Each message is automatically wrapped with metadata including a UUID for tracking. **Message Format:** Messages are automatically wrapped in the format: ```json { "data": <your_message>, "id": "<uuid>" } ```
+Broadcasts a message to all connected clients (server mode only).
 
 **Parameters:**
 
 | Name | Type | Required | Description |
 |------|------|----------|-------------|
-| `message` | `any` | ✓ | The message object to broadcast to all clients |
+| `message` | `any` | ✓ | The message object to broadcast |
+| `exclude` | `string` |  | Optional client ID to exclude from broadcast |
 
-**Returns:** `void`
+**Returns:** `this`
 
-```ts
-// Broadcast to all connected clients
-ipc.broadcast({ 
- type: 'notification',
- message: 'Server is shutting down in 30 seconds',
- timestamp: Date.now()
-});
 
-// Chain multiple operations
-ipc.broadcast({ status: 'ready' })
-  .broadcast({ time: new Date().toISOString() });
-```
+
+### sendTo
+
+Sends a message to a specific client by ID (server mode only).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `clientId` | `string` | ✓ | The target client ID |
+| `message` | `any` | ✓ | The message to send |
+
+**Returns:** `boolean`
 
 
 
 ### send
 
-Sends a message to the server (client mode only). This method sends a JSON-encoded message with a unique ID to the connected server. The message is automatically wrapped with metadata for tracking purposes. **Message Format:** Messages are automatically wrapped in the format: ```json { "data": <your_message>, "id": "<uuid>" } ```
+Fire-and-forget: sends a message to the server (client mode only). For server→client, use sendTo() or broadcast().
 
 **Parameters:**
 
 | Name | Type | Required | Description |
 |------|------|----------|-------------|
-| `message` | `any` | ✓ | The message object to send to the server |
+| `message` | `any` | ✓ | The message to send |
 
-**Returns:** `void`
+**Returns:** `Promise<void>`
 
-```ts
-// Send a simple message
-await ipc.send({ type: 'ping' });
 
-// Send complex data
-await ipc.send({
- type: 'data_update',
- payload: { users: [...], timestamp: Date.now() }
-});
-```
+
+### ask
+
+Sends a message and waits for a correlated reply. Works in both client and server mode. The recipient should call `reply(requestId, response)` to respond.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `message` | `any` | ✓ | The message to send |
+| `options` | `{ clientId?: string; timeoutMs?: number }` |  | Optional: clientId (server mode target), timeoutMs |
+
+**Returns:** `Promise<any>`
+
+
+
+### reply
+
+Sends a reply to a previous ask() call, correlated by requestId.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `requestId` | `string` | ✓ | The requestId from the incoming message |
+| `data` | `any` | ✓ | The reply payload |
+| `clientId` | `string` |  | Target client (server mode; for client mode, omit) |
+
+**Returns:** `void`
 
 
 
 ### connect
 
-Connects to an IPC server at the specified socket path (client mode). This method establishes a client connection to an existing IPC server. Once connected, the client can send messages to the server and receive responses. The connection is maintained until explicitly closed or the server terminates. **Connection Behavior:** - Sets the socket mode to 'client' - Returns existing connection if already connected - Automatically handles connection events and cleanup - JSON-parses incoming messages and emits 'message' events - Cleans up connection reference when socket closes **Error Handling:** - Throws error if already in server mode - Rejects promise on connection failures - Automatically cleans up on connection close
+Connects to an IPC server at the specified socket path (client mode).
 
 **Parameters:**
 
 | Name | Type | Required | Description |
 |------|------|----------|-------------|
-| `socketPath` | `string` | ✓ | The file system path to the server's Unix domain socket |
+| `socketPath` | `string` | ✓ | Path to the server's Unix domain socket |
+| `options` | `{ reconnect?: boolean; name?: string }` |  | Optional: reconnect (enable auto-reconnect), name (identify this client) |
 
 **Returns:** `Promise<Socket>`
 
-```ts
-// Connect to server
-const socket = await ipc.connect('/tmp/myapp.sock');
-console.log('Connected to IPC server');
 
-// Handle incoming messages
-ipc.on('message', (data) => {
- console.log('Server message:', data);
-});
 
-// Send messages
-await ipc.send({ type: 'hello', client_id: 'client_001' });
-```
+### disconnect
+
+Disconnects the client and stops any reconnection attempts.
+
+**Returns:** `void`
+
+
+
+### probeSocket
+
+Probe an existing socket to see if a live listener is behind it. Attempts a quick connect — if it succeeds, someone is listening.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `socketPath` | `string` | ✓ | Parameter socketPath |
+
+**Returns:** `Promise<boolean>`
 
 
 
@@ -146,12 +178,20 @@ await ipc.send({ type: 'hello', client_id: 'client_001' });
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `isClient` | `any` | Checks if the IPC socket is operating in client mode. |
-| `isServer` | `any` | Checks if the IPC socket is operating in server mode. |
-| `connection` | `any` | Gets the current client connection socket. |
+| `isClient` | `boolean` | Checks if the IPC socket is operating in client mode. |
+| `isServer` | `boolean` | Checks if the IPC socket is operating in server mode. |
+| `clientCount` | `number` | Returns the number of currently connected clients (server mode). |
+| `connectedClients` | `Array<{ id: string; name?: string; connectedAt: number }>` | Returns info about all connected clients (server mode). |
+| `connection` | `Socket | undefined` | Gets the current client connection socket. |
 
 ## Events (Zod v4 schema)
 
+### disconnection
+
+Event emitted by IpcSocket
+
+
+
 ### connection
 
 Event emitted by IpcSocket
@@ -207,53 +247,3 @@ try {
 }
 ```
 
-
-
-**broadcast**
-
-```ts
-// Broadcast to all connected clients
-ipc.broadcast({ 
- type: 'notification',
- message: 'Server is shutting down in 30 seconds',
- timestamp: Date.now()
-});
-
-// Chain multiple operations
-ipc.broadcast({ status: 'ready' })
-  .broadcast({ time: new Date().toISOString() });
-```
-
-
-
-**send**
-
-```ts
-// Send a simple message
-await ipc.send({ type: 'ping' });
-
-// Send complex data
-await ipc.send({
- type: 'data_update',
- payload: { users: [...], timestamp: Date.now() }
-});
-```
-
-
-
-**connect**
-
-```ts
-// Connect to server
-const socket = await ipc.connect('/tmp/myapp.sock');
-console.log('Connected to IPC server');
-
-// Handle incoming messages
-ipc.on('message', (data) => {
- console.log('Server message:', data);
-});
-
-// Send messages
-await ipc.send({ type: 'hello', client_id: 'client_001' });
-```
-

package/docs/apis/features/node/networking.md

@@ -32,7 +32,7 @@ Finds the next available port starting from the specified port number. This meth
 |------|------|----------|-------------|
 | `startAt` | `any` |  | The port number to start searching from (0 means system will choose) |
 
-**Returns:** `void`
+**Returns:** `Promise<number>`
 
 ```ts
 // Find any available port
@@ -55,7 +55,7 @@ Checks if a specific port is available for use. This method attempts to detect i
 |------|------|----------|-------------|
 | `checkPort` | `any` |  | The port number to check for availability |
 
-**Returns:** `void`
+**Returns:** `Promise<boolean>`
 
 ```ts
 // Check if port 8080 is available
@@ -197,9 +197,9 @@ Convenience method: discover and port-scan hosts across all local networks.
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `proc` | `any` |  |
-| `os` | `any` |  |
-| `nmap` | `any` | Optional nmap wrapper for users that already have nmap installed. |
+| `proc` | `ReturnType<typeof this.container.feature<'proc'>>` |  |
+| `os` | `ReturnType<typeof this.container.feature<'os'>>` |  |
+| `nmap` | `{ isAvailable: () => Promise<boolean>; scan: (target: string, args?: string[]) => Promise<{ hosts: NmapHost[]; raw: string }>; quickScan: (cidr: string) => Promise<{ hosts: NmapHost[]; raw: string }>; fullScan: (target: string) => Promise<{ hosts: NmapHost[]; raw: string }> }` | Optional nmap wrapper for users that already have nmap installed. |
 
 ## Events (Zod v4 schema)
 

package/docs/apis/features/node/os.md

@@ -29,13 +29,13 @@ displays.forEach(d => {
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `arch` | `any` | Gets the operating system CPU architecture. |
-| `tmpdir` | `any` | Gets the operating system's default directory for temporary files. |
-| `homedir` | `any` | Gets the current user's home directory path. |
-| `cpuCount` | `any` | Gets the number of logical CPU cores available on the system. |
-| `hostname` | `any` | Gets the hostname of the operating system. |
-| `platform` | `any` | Gets the operating system platform. |
-| `networkInterfaces` | `any` | Gets information about the system's network interfaces. |
+| `arch` | `string` | Gets the operating system CPU architecture. |
+| `tmpdir` | `string` | Gets the operating system's default directory for temporary files. |
+| `homedir` | `string` | Gets the current user's home directory path. |
+| `cpuCount` | `number` | Gets the number of logical CPU cores available on the system. |
+| `hostname` | `string` | Gets the hostname of the operating system. |
+| `platform` | `string` | Gets the operating system platform. |
+| `networkInterfaces` | `NodeJS.Dict<os.NetworkInterfaceInfo[]>` | Gets information about the system's network interfaces. |
 | `macAddresses` | `string[]` | Gets an array of MAC addresses for non-internal IPv4 network interfaces. This filters the network interfaces to only include external IPv4 interfaces and returns their MAC addresses, which can be useful for system identification. |
 
 ## State (Zod v4 schema)

package/docs/apis/features/node/package-finder.md

@@ -57,7 +57,7 @@ finder.addPackage({
 
 Starts the package finder and performs the initial workspace scan. This method is idempotent - calling it multiple times will not re-scan if already started. It triggers the complete workspace scanning process.
 
-**Returns:** `void`
+**Returns:** `Promise<this | undefined>`
 
 ```ts
 await finder.start();
@@ -82,7 +82,7 @@ Performs a comprehensive scan of all node_modules directories in the workspace.
 |----------|------|-------------|
 | `exclude` | `any` | Optional exclusion patterns (not implemented) |
 
-**Returns:** `void`
+**Returns:** `Promise<this>`
 
 ```ts
 // Manual scan (usually called automatically by start())
@@ -104,7 +104,7 @@ Finds the first package manifest matching the given name. If multiple versions o
 |------|------|----------|-------------|
 | `name` | `string` | ✓ | The exact package name to search for |
 
-**Returns:** `void`
+**Returns:** `PartialManifest | undefined`
 
 ```ts
 const lodash = finder.findByName('lodash');
@@ -125,7 +125,7 @@ Finds all packages that declare the specified package as a dependency. Searches
 |------|------|----------|-------------|
 | `packageName` | `string` | ✓ | The name of the package to find dependents for |
 
-**Returns:** `void`
+**Returns:** `PartialManifest[]`
 
 ```ts
 const reactDependents = finder.findDependentsOf('react');
@@ -147,7 +147,7 @@ Finds the first package manifest matching the provided filter function.
 |------|------|----------|-------------|
 | `filter` | `(manifest: PartialManifest) => boolean` | ✓ | Function that returns true for matching packages |
 
-**Returns:** `void`
+**Returns:** `PartialManifest | undefined`
 
 ```ts
 // Find a package with specific version
@@ -169,7 +169,7 @@ Finds all package manifests matching the provided filter function.
 |------|------|----------|-------------|
 | `filter` | `(manifest: PartialManifest) => boolean` | ✓ | Function that returns true for matching packages |
 
-**Returns:** `void`
+**Returns:** `PartialManifest[]`
 
 ```ts
 // Find all packages with 'babel' in the name
@@ -194,7 +194,7 @@ Returns all packages that do NOT match the provided filter function. This is the
 |------|------|----------|-------------|
 | `filter` | `(manifest: PartialManifest) => boolean` | ✓ | Function that returns true for packages to exclude |
 
-**Returns:** `void`
+**Returns:** `PartialManifest[]`
 
 ```ts
 // Get all non-development packages (those not in devDependencies)
@@ -208,7 +208,7 @@ const unscoped = finder.exclude(pkg => pkg.name.startsWith('@'));
 
 ### findLocalPackageFolders
 
-**Returns:** `void`
+**Returns:** `Promise<string[]>`
 
 
 
@@ -216,12 +216,12 @@ const unscoped = finder.exclude(pkg => pkg.name.startsWith('@'));
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `duplicates` | `any` | Gets a list of package names that have multiple versions/instances installed. This is useful for identifying potential dependency conflicts or opportunities for deduplication in the project. |
-| `isStarted` | `any` | Checks if the package finder has completed its initial scan. |
-| `packageNames` | `any` | Gets an array of all unique package names discovered in the workspace. |
-| `scopes` | `any` | Gets an array of all scoped package prefixes found in the workspace. Scoped packages are those starting with '@' (e.g., @types/node, @babel/core). This returns just the scope part (e.g., '@types', '@babel'). |
-| `manifests` | `any` | Gets a flat array of all package manifests found in the workspace. This includes all versions/instances of packages, unlike packageNames which returns unique names only. |
-| `counts` | `any` | Gets a count of instances for each package name. Useful for quickly identifying which packages have multiple versions and how many instances of each exist. |
+| `duplicates` | `string[]` | Gets a list of package names that have multiple versions/instances installed. This is useful for identifying potential dependency conflicts or opportunities for deduplication in the project. |
+| `isStarted` | `boolean` | Checks if the package finder has completed its initial scan. |
+| `packageNames` | `string[]` | Gets an array of all unique package names discovered in the workspace. |
+| `scopes` | `string[]` | Gets an array of all scoped package prefixes found in the workspace. Scoped packages are those starting with '@' (e.g., @types/node, @babel/core). This returns just the scope part (e.g., '@types', '@babel'). |
+| `manifests` | `(PartialManifest & { __path: string })[]` | Gets a flat array of all package manifests found in the workspace. This includes all versions/instances of packages, unlike packageNames which returns unique names only. |
+| `counts` | `Record<string, number>` | Gets a count of instances for each package name. Useful for quickly identifying which packages have multiple versions and how many instances of each exist. |
 
 ## State (Zod v4 schema)
 

package/docs/apis/features/node/proc.md

@@ -70,6 +70,7 @@ Spawns a process and captures its output with real-time monitoring capabilities.
 | `onError` | `(data: string) => void` | Callback invoked when stderr data is received |
 | `onOutput` | `(data: string) => void` | Callback invoked when stdout data is received |
 | `onExit` | `(code: number) => void` | Callback invoked when the process exits |
+| `onStart` | `(childProcess: ChildProcess) => void` | Callback invoked when the process starts |
 
 **Returns:** `Promise<{
     stderr: string;
@@ -126,7 +127,7 @@ Spawn a raw child process and return the handle immediately. Useful when callers
 | `stdout` | `"pipe" | "inherit" | "ignore"` | Stdout mode for the child process |
 | `stderr` | `"pipe" | "inherit" | "ignore"` | Stderr mode for the child process |
 
-**Returns:** `void`
+**Returns:** `import('child_process').ChildProcess`
 
 
 

package/docs/apis/features/node/process-manager.md

@@ -1,6 +1,6 @@
 # ProcessManager (features.processManager)
 
-Manages long-running child processes with tracking, events, and automatic cleanup. Unlike the `proc` feature whose spawn methods block until the child exits, ProcessManager returns a SpawnHandler immediately — a handle object with its own state, events, and lifecycle methods. The feature tracks all spawned processes, maintains observable state, and can automatically kill them on parent exit.
+Manages long-running child processes with tracking, events, and automatic cleanup. Unlike the `proc` feature whose spawn methods block until the child exits, ProcessManager returns a SpawnHandler immediately — a handle object with its own state, events, and lifecycle methods. The feature tracks all spawned processes, maintains observable state, and can automatically kill them on parent exit. Each handler maintains a memory-efficient output buffer: the first 20 lines (head) and last 50 lines (tail) of stdout/stderr are kept, everything in between is discarded.
 
 ## Usage
 
@@ -19,6 +19,70 @@ container.feature('processManager', {
 
 ## Methods
 
+### spawnProcess
+
+Tool handler: spawn a long-running background process.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ command: string; args?: string; tag?: string; cwd?: string }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
+### runCommand
+
+Tool handler: run a command to completion and return its output.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ command: string; cwd?: string }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
+### listProcesses
+
+Tool handler: list all tracked processes.
+
+**Returns:** `void`
+
+
+
+### getProcessOutput
+
+Tool handler: peek at a process's buffered output.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ id?: string; tag?: string; stream?: string }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
+### killProcess
+
+Tool handler: kill a process by ID or tag.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ id?: string; tag?: string; signal?: string }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
 ### spawn
 
 Spawn a long-running process and return a handle immediately. The returned SpawnHandler provides events for stdout/stderr streaming, exit/crash notifications, and methods to kill or await the process.
@@ -157,7 +221,7 @@ Emitted when a new process is spawned
 | Name | Type | Description |
 |------|------|-------------|
 | `arg0` | `string` | process ID |
-| `arg1` | `any` | process metadata |
+| `arg1` | `string` | process metadata |
 
 
 
@@ -184,7 +248,7 @@ Emitted when a process exits with non-zero code
 |------|------|-------------|
 | `arg0` | `string` | process ID |
 | `arg1` | `number` | exit code |
-| `arg2` | `any` | error info |
+| `arg2` | `string` | error info |
 
 
 
@@ -225,6 +289,9 @@ const server = pm.spawn('node', ['server.js'], { tag: 'api', cwd: '/app' })
 server.on('stdout', (data) => console.log('[api]', data))
 server.on('crash', (code) => console.error('API crashed:', code))
 
+// Peek at buffered output
+const { head, tail } = server.peek()
+
 // Kill one
 server.kill()