luca 3.0.0 → 3.0.2

package/docs/challenges/grep-audit-report.md

@@ -1,15 +0,0 @@
-# Grep Audit Report
-
-Build `luca audit <path>` that scans a codebase at the given path and finds:
-
-- TODO and FIXME comments
-- `console.log` statements
-- Hardcoded secret patterns (strings that look like API keys, tokens, passwords in assignments)
-
-Generate a markdown report at `docs/reports/audit-<timestamp>.md` summarizing the findings with file paths and line numbers.
-
-Support `luca audit <path> --json` for machine-readable output instead of markdown.
-
-## After you are done
-
-Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/challenges/multi-feature-dashboard.md

@@ -1,14 +0,0 @@
-# Build a Multi-Feature Dashboard
-
-Create a `luca dashboard` command that displays a live-updating terminal UI showing:
-
-- Git status: current branch, number of dirty files
-- Cache stats: number of cached entries
-- OS info: CPU usage, free memory
-- Network: whether https://example.com is reachable
-
-The dashboard should refresh every 2 seconds with a nice terminal layout.
-
-## After you are done
-
-Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/challenges/process-orchestrator.md

@@ -1,17 +0,0 @@
-# Process Orchestrator
-
-Build `luca dev` that starts 3 processes simultaneously:
-
-1. An HTTP API server on port 3000
-2. A WebSocket server on port 3001
-3. A file watcher that logs changes in the project directory
-
-Multiplex their logs to stdout with color-coded prefixes (e.g. `[API]`, `[WS]`, `[WATCH]`). Gracefully shut down all processes on ctrl+c.
-
-Support `luca dev --only api,ws` to start a subset of the processes.
-
-Create a simple endpoint and websocket handler so there's something to actually hit when testing.
-
-## After you are done
-
-Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/challenges/rest-api-server-with-client.md

@@ -1,12 +0,0 @@
-# Build a REST server with a matching REST Client
-
-Create a command `luca start` which will use a custom luca express server you build and start it.
-
-Also create a rest client that can call the methods it exposes.
-
-The `luca connect` command should use the client and verify that all the servers endpoints work.
-
-
-## After you are done
-
-Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/challenges/script-runner-with-vm.md

@@ -1,11 +0,0 @@
-# Script Runner with VM
-
-Create a `scripts/` folder with a few `.ts` files that each export a `run()` function. These scripts should do simple things — format a date, generate a UUID, compute a hash of some input.
-
-Build a `luca exec <scriptName>` command that loads and runs the named script in a sandboxed environment. The script should have access to the container but not direct filesystem access.
-
-Add `luca exec --list` to show all available scripts with a short description parsed from a comment or export in each file.
-
-## After you are done
-
-Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/challenges/simple-rest-api.md

@@ -1,15 +0,0 @@
----
-lastRanAt: 1773554828927
-durationMs: 601701
-outputTokens: 1646
----
-
-# Build an API
-
-I should be able to serve the api with `luca serve`
-
-The API should use sqlite to serve an example api that lets me browse authors and books.
-
-## After you are done
-
-Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/challenges/websocket-serve-and-client.md

@@ -1,11 +0,0 @@
-# Build a websocket server with a matching websocket client
-
-Use the luca framework to build a websocket server you can start with a `luca start` command.
-
-Also build a websocket based client that can connect to that server and speak the same language ( as opposed to just raw websocket calls )
-
-Create a command called `luca connect` that uses this client and verifies that the server responds as expected.
-
-## After you are done
-
-Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/challenges/yaml-config-system.md

@@ -1,14 +0,0 @@
-# YAML Config System
-
-Build a command suite for managing project configuration stored in `luca.config.yaml`:
-
-- `luca config set <key> <value>` — set a config value (support nested keys like `server.port`)
-- `luca config get <key>` — get a config value
-- `luca config list` — print the full config as a formatted table
-- `luca config delete <key>` — remove a key
-
-Create the config file if it doesn't exist.
-
-## After you are done
-
-Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/command-system-overhaul.md

@@ -1,94 +0,0 @@
-# Command System Overhaul
-
-The command system was pretty much 100% vibe coded and not reviewed.  It was only until the first round of evals that I noticed some issues with it and dug into the code and noticed a few things with its implementation that are not consistent with the rest of the project.
-
-My main issue is it doesn't actually use the luca Registry, the Command is not even a subclass of Helper, even though it is easily one of the most obvious examples, however there are quirks to it that let me empathize with the agent for its choices, so I want to resolve those conflicts so we can arrive at the correct design.
-
-## Original Vision For Commands
-
-1) For a user of the compiled `luca` binary, any `commands/:commandName.ts` will be available as `luca commandName` 
-2) The luca framework itself comes with core commands in `src/commands/*` that are bundled with the `luca` binary from bun
-3) A user can also have `~/.luca/commands` folder which gets picked up
-4) commands can export a zod schema that can be used for validation, documentation for CLI help screens
-
-## Command Helper Options / State 
-
-A Command's constructor options are higher level things about the environment the command is being invoked in:
-
-- target ( cli (output to stdout, stderr etc), headless (e.g. run through the js api in code, stdout, stderr needs to be captured and returned) 
-
-
-## Developer Experience Requirements
-
-Unlike features, clients, servers, which necessarily require a lot more forethought, a command should be very quick to author
-
-for this reason, there needs to be a way that we can dynamically generate Command helper subclasses, without requiring the user to go through the ceremony of doing that.
-
-Instead, a command module should be able to simply export a couple of expected named objects / types, and have the Command helper subclass generated and registered in the command registry at runtime.
-
-## Idea for General Reusable DX Feature
-
-This approach will allow us to accomplish the DX requirement for commands in a way that could make authoring every type of helper simpler as well, without having to modify the core class based implementation. 
-
-Given a typescript module called serve
-
-
-```ts
-import type { SimpleCommand } from '@soederpop/luca'
-
-// SimpleCommand is a ts generic that makes it simpler to construct the actual class ServeCommand<CommandHelperOptions,COmmandHelperState> since all commands share the same base constructor options and have the same state, but we will need to capture
-// the run options schema 
-declare module '@soederpop/luca' {
-  interface AvailableCommands {
-    serve: typeof Command  
-  }
-}
-
-
-// container is gonna be global here if they don't import anything
-// because this module will be run through the container's vm instead of being directly imported
-const runOptionsSchema = z.object({
-
-})
-
-export type ServeRunOptions = z.infer<typeof runOptionsSchema> 
-
-export async function run(options: ServeRunOptions) {
-
-}
-```
-
-This module could be grafted on to a subclass that gets generated at runtime and meets all the requirements 
-
-## CLI Internal Implementation idea 
-
-This is pseudocode, but will illustrate how I think we can accomplish the above.
-
-The CLI would just call the execute method with whatever container.argv is as its input (container.argv is the result of minimist)
-
-Any other kind of dispatcher that is using commands and wants to accept arbitrary subclasses can also use this execute method, and not have to worry about the simple command overriding the run method
-
-```ts
-type CommandOptions, CommandState etc ( zod schema inferred, make sure to follow feature, client, server implementations )
-
-class Command extends Helper<CommandOptions,CommandState,COmmandEvents> {
-    // private, but we should allow the CLI to reach in and call this ?
-    private async execute(params) {
-        return this.run(params)
-    }
-    
-    // NOTE: CommandRunOptions is not the same as the CommandOptions or HelperOptions passed to the constructor
-    // In fact the command options are more high level (e.g, is it running from the CLI? dispatched over RPC, an MCP call
-    // an agent tool? Commands are just atomic units of work that can be requested.
-    run(options: CommandRunOptions) {
-        // you don't need to super this ever, any subclass of command implements its own run
-        // SimpleCommands can export run and safely override this, because the CLI doesn't call run directly it calls execute
-    }
-}
-```
-
-
-
-
-
-

package/docs/documentation-audit.md

@@ -1,134 +0,0 @@
-# Documentation Audit
-
-Periodically do an audit of all Feature, Server, Client subclasses to make sure they are completely documented.
-
-
-## Files
-
-- `src/node/features/*.ts` NodeContainer features
-- `src/clients/*/index.ts` Client subclasses
-- `src/agi/features.ts` AGIContainer features
-
-## Generating Introspection Data for Runtime consumption
-
-After any changes to the above files, make sure to run:
-
-```shell
-bun run build:introspection 
-```
-
-## Documentation Guidelines
-
-Here is a good example of a well documented feature, notice that:
-
-- All of the Options, State, Event schema items have `describe()` calls
-- There is a docblock above the class which uses a simple example with no imports, using the factory pattern
-- getters are documented
-- methods have jsdoc also with an example
-- method options have jsdoc comments for typescript consumers
-
-```ts
-
-export const TTSOptionsSchema = FeatureOptionsSchema.extend({
-  apiKey: z.string().optional().describe('RunPod API key (falls back to RUNPOD_API_KEY env var)'),
-  voice: z.string().optional().describe('Default preset voice name'),
-  outputDir: z.string().optional().describe('Directory to save generated audio files'),
-  format: z.enum(['wav', 'flac', 'ogg']).default('wav').describe('Audio output format'),
-})
-export type TTSOptions = z.infer<typeof TTSOptionsSchema>
-
-export const TTSStateSchema = FeatureStateSchema.extend({
-  lastFile: z.string().optional().describe('Path to the last generated audio file'),
-  lastText: z.string().optional().describe('Text of the last synthesis request'),
-  generating: z.boolean().default(false).describe('Whether audio is currently being generated'),
-})
-export type TTSState = z.infer<typeof TTSStateSchema>
-
-export const TTSEventsSchema = FeatureEventsSchema.extend({
-  synthesized: z.tuple([
-    z.string().describe('The text that was synthesized'),
-    z.string().describe('Path to the generated audio file'),
-    z.string().describe('Voice used'),
-    z.number().describe('Duration of the API call in milliseconds'),
-  ]).describe('Emitted when audio synthesis completes'),
-  error: z.tuple([
-    z.any().describe('The error'),
-  ]).describe('Emitted when synthesis fails'),
-})
-
-/**
- * TTS feature — synthesizes text to audio files via RunPod's Chatterbox Turbo endpoint.
- *
- * Generates high-quality speech audio by calling the Chatterbox Turbo public endpoint
- * on RunPod, downloads the resulting audio, and saves it locally. Supports 20 preset
- * voices and voice cloning via a reference audio URL.
- *
- * @example
- * ```typescript
- * const tts = container.feature('tts', { enable: true })
- * const path = await tts.synthesize('Hello, how are you?', { voice: 'lucy' })
- * console.log(`Audio saved to: ${path}`)
- * ```
- */
-export class TTS extends Feature<TTSState, TTSOptions> {
-  static override shortcut = 'features.tts' as const
-  static override envVars = ['RUNPOD_API_KEY']
-  static override stateSchema = TTSStateSchema
-  static override optionsSchema = TTSOptionsSchema
-  static override eventsSchema = TTSEventsSchema
-
-  /** RunPod API key from options or environment. */
-  get apiKey(): string {
-    return this.options.apiKey || process.env.RUNPOD_API_KEY || ''
-  }
-
-  /** Directory where generated audio files are saved. */
-  get outputDir(): string {
-    return this.options.outputDir || join(homedir(), '.luca', 'tts-cache')
-  }
-
-  /** The 20 preset voice names available in Chatterbox Turbo. */
-  get voices(): readonly string[] {
-    return PRESET_VOICES
-  }
-
-  /**
-   * Synthesize text to an audio file using Chatterbox Turbo.
-   *
-   * Calls the RunPod public endpoint, downloads the generated audio,
-   * and saves it to the output directory.
-   *
-   * @param text - The text to synthesize into speech
-   * @param options - Override voice, format, or provide a voiceUrl for cloning
-   * @returns Absolute path to the generated audio file
-   *
-   * @example
-   * ```typescript
-   * // Use a preset voice
-   * const path = await tts.synthesize('Good morning!', { voice: 'ethan' })
-   *
-   * // Clone a voice from a reference audio URL
-   * const path = await tts.synthesize('Hello world', {
-   *   voiceUrl: 'https://example.com/reference.wav'
-   * })
-   * ```
-   */
-  async synthesize(text: string, options?: {
-		/* which voice to use */
-    voice?: string
-		/* which format to save the output in */
-    format?: 'wav' | 'flac' | 'ogg'
-		/* an optional url to use for voice cloning */
-    voiceUrl?: string
-  }): Promise<string> {
-    if (!this.apiKey) {
-      throw new Error('TTS requires a RunPod API key. Set RUNPOD_API_KEY or pass apiKey in options.')
-    }
-		// omitted
-	}
-
-}
-
-```
-
-

package/docs/examples/assistant/CORE.md

@@ -1,18 +0,0 @@
-# Luca Assistant Example
-
-You are currently an example / template "Assistant" provided by the Luca framework.  ( You'll probably have no idea what that is, don't worry, it doesn't matter ).
-
-You are what gets scaffolded when a user writes the `luca scaffold assistant` command.
-
-In luca, an Assistant is backed by a folder which has a few components:
-
-- CORE.md -- this is a markdown file that will get injected into the system prompt of a chat completion call
-- tools.ts -- this file is expected to export functions, and a schemas object whose keys are the names of the functions that get exported, and whose values are zod v4 schemas that describe the parameters
-- hooks.ts -- this file is expexted to export functions, whose names match the events emitted by the luca assistant helper
-
-Currently, the user is chatting with you from the `luca chat` CLI.  
-
-You should tell them what each of these files is and how to edit them.
-
-It is also important for them to know that the luca `container` is globally available for them in the context of the `tools.ts` and `hooks.ts` files.
-

package/docs/examples/assistant/hooks.ts

@@ -1,3 +0,0 @@
-export function started() {
-	console.log('Assistant started!')
-}

package/docs/examples/assistant/tools.ts

@@ -1,10 +0,0 @@
-import { z } from 'zod'
-
-export const schemas = {
-	README: z.object({}).describe('CALL THIS README FUNCTION AS EARLY AS POSSIBLE')
-}
-
-export function README(options: z.infer<typeof schemas.README>) {
-	return 'YO YO'
-}
-

package/docs/examples/assistant-hooks-reference.ts

@@ -1,171 +0,0 @@
-/**
- * Example hooks.ts — showcases the assistant hook system.
- *
- * Every named export is a hook. Hooks are awaited via triggerHook(),
- * so async work completes BEFORE the assistant proceeds.
- *
- * Available hooks:
- *
- *   Lifecycle:
- *     created()              — after prompt/tools/hooks load (before start)
- *     beforeStart()          — before conversation wiring, blocks start()
- *     started()              — conversation is ready, wire up tools here
- *     afterStart()           — everything is live, blocks start() until done
- *     formatSystemPrompt(a, prompt) => string — rewrite the system prompt
- *
- *   Ask flow:
- *     beforeInitialAsk(a, question, options) — first ask() only
- *     beforeAsk(a, question, options) => string? — every ask(), return rewrites question
- *     answered(a, result) — after response, before ask() returns
- *
- *   Tool execution:
- *     beforeToolCall(a, ctx) — inspect/rewrite args, set ctx.skip to bypass
- *     afterToolCall(a, ctx)  — inspect/rewrite result after execution
- *
- *   Forwarded from conversation (awaited before the bus event):
- *     turnStart(a, info)  turnEnd(a, info)  chunk(a, delta)
- *     preview(a, text)    response(a, text)  toolCall(a, name, args)
- *     toolResult(a, name, result)  toolError(a, name, error)
- *
- * The first argument is always the assistant instance.
- * `assistant` and `container` are also available as globals (injected by the VM).
- */
-import type { Assistant, AGIContainer } from '@soederpop/luca/agi'
-
-declare global {
-  var assistant: Assistant
-  var container: AGIContainer
-}
-
-// ─── Lifecycle ──────────────────────────────────────────────────
-
-/**
- * Runs before the conversation is created. Good for async setup
- * that needs to finish before the assistant is usable.
- */
-export async function beforeStart() {
-  console.log(`[hooks] preparing ${assistant.assistantName}...`)
-}
-
-/**
- * Conversation is wired — register tools, plugins, extensions.
- * This is the most common hook: equivalent to the old bus-based pattern.
- */
-export function started() {
-  // Give the assistant shell tools
-  assistant.use(container.feature('codingTools'))
-
-  // Add write operations from fileTools
-  const fileTools = container.feature('fileTools')
-  assistant.use(fileTools.toTools({ only: ['editFile', 'writeFile'] }))
-  fileTools.setupToolsConsumer(assistant)
-}
-
-/**
- * Everything is live. Good for loading state that depends on
- * the conversation being fully initialized. Blocks start().
- */
-export async function afterStart() {
-  // e.g. load a knowledge base into the system prompt
-  const fs = container.feature('fs')
-  const notesPath = assistant.paths.resolve('notes.md')
-
-  if (await fs.exists(notesPath)) {
-    const notes = await fs.readFile(notesPath)
-    assistant.addSystemPromptExtension('notes', `\n## Your Notes\n${notes}`)
-  }
-}
-
-/**
- * Rewrite the system prompt before the conversation is created.
- * Return the new prompt string.
- */
-export async function formatSystemPrompt(_assistant: Assistant, prompt: string) {
-  const today = new Date().toLocaleDateString('en-US', {
-    weekday: 'long', year: 'numeric', month: 'long', day: 'numeric',
-  })
-  return `${prompt}\n\nToday is ${today}.`
-}
-
-// ─── Ask Flow ───────────────────────────────────────────────────
-
-/**
- * Runs only on the very first ask(). Good for one-time greetings
- * or loading context that depends on the first user message.
- */
-export async function beforeInitialAsk(_assistant: Assistant, question: string) {
-  console.log(`[hooks] first message from user: "${question}"`)
-}
-
-/**
- * Runs before every ask(). Return a string to rewrite the question.
- * Useful for injecting context the model should see but the user
- * shouldn't have to type every time.
- */
-export async function beforeAsk(_assistant: Assistant, question: string) {
-  // Example: inject recent git context into every question
-  const proc = container.feature('proc')
-  const { stdout } = await proc.exec('git log --oneline -5 2>/dev/null || true')
-
-  if (stdout.trim()) {
-    return `${question}\n\n<context>\nRecent commits:\n${stdout.trim()}\n</context>`
-  }
-}
-
-/**
- * Fires after the model responds, before ask() returns.
- * Good for logging, analytics, or auto-saving.
- */
-export async function answered(_assistant: Assistant, result: string) {
-  console.log(`[hooks] response length: ${result.length} chars`)
-}
-
-// ─── Tool Execution ─────────────────────────────────────────────
-
-/**
- * Fires before every tool call. The ctx object is mutable:
- *   ctx.name  — tool name
- *   ctx.args  — arguments (rewrite to modify)
- *   ctx.skip  — set true to bypass execution
- *   ctx.result — set when skipping to provide a result
- */
-export async function beforeToolCall(_assistant: Assistant, ctx: any) {
-  console.log(`[hooks] tool call: ${ctx.name}(${JSON.stringify(ctx.args)})`)
-
-  // Example: block dangerous commands
-  if (ctx.name === 'runCommand' && ctx.args.command?.includes('rm -rf')) {
-    ctx.skip = true
-    ctx.result = JSON.stringify({ error: 'Blocked: destructive command not allowed' })
-  }
-}
-
-/**
- * Fires after every tool call. The ctx object contains:
- *   ctx.name   — tool name
- *   ctx.args   — original arguments
- *   ctx.result — the result string (rewrite to modify what the model sees)
- *   ctx.error  — error object if the tool threw
- */
-export async function afterToolCall(_assistant: Assistant, ctx: any) {
-  if (ctx.error) {
-    console.error(`[hooks] tool ${ctx.name} failed:`, ctx.error.message)
-  }
-
-  // Example: truncate huge tool outputs so they don't blow the context
-  if (ctx.result && ctx.result.length > 10000) {
-    const truncated = ctx.result.slice(0, 10000)
-    ctx.result = `${truncated}\n\n... (truncated from ${ctx.result.length} chars)`
-  }
-}
-
-// ─── Forwarded Conversation Events ──────────────────────────────
-
-/**
- * Fires at the start of each completion turn. turn > 1 means
- * the model is continuing after tool calls.
- */
-export function turnStart(_assistant: Assistant, info: { turn: number; isFollowUp: boolean }) {
-  if (info.isFollowUp) {
-    console.log(`[hooks] follow-up turn ${info.turn}`)
-  }
-}

package/docs/examples/assistant-with-process-manager.md

@@ -1,84 +0,0 @@
----
-title: "Assistant with ProcessManager Tools"
-tags: [assistant, processManager, tools, runtime, use]
-lastTested: null
-lastTestPassed: null
----
-
-# Assistant with ProcessManager Tools
-
-Create an assistant at runtime, give it processManager tools, and watch it orchestrate long-running processes — spawning ping and top, checking their output over time, running a quick command in between, then coming back to report.
-
-## The Demo
-
-```ts
-const pm = container.feature('processManager', { enable: true, autoCleanup: true })
-const ui = container.feature('ui')
-
-const assistant = container.feature('assistant', {
-  systemPrompt: [
-    'You are a process management assistant with tools to spawn, monitor, inspect, and kill background processes.',
-    'When asked to check on processes, use getProcessOutput to read their latest output and summarize what you see.',
-    'For ping output, parse the lines and calculate the average response time yourself.',
-    'For top output, summarize CPU and memory usage from the header lines.',
-    'Always be concise — give the data, not a lecture.',
-  ].join('\n'),
-  model: 'gpt-4.1-mini',
-})
-
-assistant.use(pm)
-await assistant.start()
-
-const tools = Object.keys(assistant.tools)
-console.log(ui.colors.cyan('Tools registered:'), tools.join(', '))
-console.log()
-
-// ── Helper to print assistant responses ──────────────────────────────
-const ask = async (label, question) => {
-  console.log(ui.colors.dim(`── ${label} ──`))
-  console.log(ui.colors.yellow('→'), question.split('\n')[0])
-  const response = await assistant.ask(question)
-  console.log(ui.markdown(response))
-  console.log()
-  return response
-}
-
-// Step 1: Spawn long-running processes
-await ask('SPAWN',
-  'Spawn two background processes:\n' +
-  '1. Ping google.com with tag "ping-google" (use: ping -c 20 google.com)\n' +
-  '2. Run top in batch mode with tag "top-monitor" (use: top -l 5 -s 2)\n' +
-  'Confirm both are running.'
-)
-
-// Step 2: Wait, then check in on their output
-await new Promise(r => setTimeout(r, 4000))
-await ask('CHECK-IN #1',
-  'Check on both processes. For ping-google, read the stdout and tell me how many replies so far and the average response time. For top-monitor, read the stdout and tell me the current CPU usage summary.'
-)
-
-// Step 3: Quick one-shot command while the others keep going
-await ask('QUICK COMMAND',
-  'Run a quick command: "uptime" — tell me the system load averages.'
-)
-
-// Step 4: Second check-in — more data should have accumulated
-await new Promise(r => setTimeout(r, 4000))
-await ask('CHECK-IN #2',
-  'Check on ping-google again. How many replies now vs last time? What is the average response time? Also list all tracked processes and their status.'
-)
-
-// Step 5: Kill everything
-await ask('CLEANUP',
-  'Kill all running processes and confirm they are stopped.'
-)
-
-// Belt and suspenders
-pm.killAll()
-const remaining = pm.list().filter(h => h.status === 'running')
-console.log(ui.colors.green('Running after cleanup:'), remaining.length)
-```
-
-## Summary
-
-This example showed a runtime assistant orchestrating real background processes over multiple conversation turns — spawning long-running `ping` and `top` commands, checking in on their output as it accumulates, running a quick `uptime` in between, then coming back for a second check-in before cleaning everything up. The assistant parsed ping times, summarized CPU usage, and managed the full lifecycle without any hardcoded logic — just natural language and processManager tools.