@ai-agent-forge/agent-forge 0.85.0

package/examples/sdk/README.md

@@ -0,0 +1,139 @@
+# SDK Examples
+
+Programmatic usage of `@agent-forge/agent-forge` via the stable entries `createStableAgentSession()` and, for session replacement, `createStableAgentSessionRuntime()`.
+
+The runtime example (13) shows how to build a recreate function that closes over process-global fixed inputs and recreates cwd-bound services and sessions as the active session cwd changes; it goes through the stable runtime entry and reads the current session through `runtimeFacade.getSessionFacade()`. The other eleven examples go through the stable facade pair (`{ facade, sessionAPI }`) from `createStableAgentSession()`; the session-persistence example (11) reads the create-time model fallback diagnostic off the stable create result.
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| `01-minimal.ts` | Simplest usage with all defaults |
+| `02-custom-model.ts` | Select model and thinking level |
+| `03-custom-prompt.ts` | Replace or modify system prompt |
+| `04-skills.ts` | Discover, filter, or replace skills |
+| `05-tools.ts` | Built-in tool allowlists |
+| `07-context-files.ts` | AGENTS.md context files |
+| `08-prompt-templates.ts` | File-based slash commands |
+| `09-api-keys-and-oauth.ts` | API key resolution, OAuth config |
+| `10-settings.ts` | Override compaction, retry, terminal settings |
+| `11-sessions.ts` | In-memory, persistent, continue, list sessions |
+| `12-full-control.ts` | Replace everything, no discovery |
+| `13-session-runtime.ts` | Stable runtime entry: replace the active session (newSession/switchSession/fork) |
+
+## Running
+
+```bash
+cd packages/agent-forge
+npx tsx examples/sdk/01-minimal.ts
+```
+
+## Quick Reference
+
+```typescript
+import { getModel } from "@agent-forge/ai";
+import {
+  createStableAgentSession,
+  DefaultResourceLoader,
+  ModelRuntime,
+  SessionManager,
+  SettingsManager,
+} from "@agent-forge/agent-forge";
+
+const modelRuntime = await ModelRuntime.create();
+
+// Minimal
+const { facade } = await createStableAgentSession({ modelRuntime });
+
+// Custom model
+const model = getModel("anthropic", "claude-opus-4-5");
+const { facade } = await createStableAgentSession({ model, thinkingLevel: "high", modelRuntime });
+
+// Modify prompt
+const loader = new DefaultResourceLoader({
+  systemPromptOverride: (base) => `${base}\n\nBe concise.`,
+});
+await loader.reload();
+const { facade } = await createStableAgentSession({ resourceLoader: loader, modelRuntime });
+
+// Read-only
+const { facade } = await createStableAgentSession({ tools: ["read", "grep", "find", "ls"], modelRuntime });
+
+// In-memory
+const { facade } = await createStableAgentSession({
+  sessionManager: SessionManager.inMemory(),
+  modelRuntime,
+});
+
+// Full control
+const customRuntime = await ModelRuntime.create({
+  authPath: "/my/app/auth.json",
+  modelsPath: "/my/app/models.json",
+});
+await customRuntime.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
+
+const resourceLoader = new DefaultResourceLoader({
+  systemPromptOverride: () => "You are helpful.",
+  extensionFactories: [myExtension],
+  skillsOverride: () => ({ skills: [], diagnostics: [] }),
+  agentsFilesOverride: () => ({ agentsFiles: [] }),
+  promptsOverride: () => ({ prompts: [], diagnostics: [] }),
+});
+await resourceLoader.reload();
+
+const { facade } = await createStableAgentSession({
+  model,
+  modelRuntime: customRuntime,
+  resourceLoader,
+  tools: ["read", "bash", "my_tool"],
+  customTools: [myTool],
+  sessionManager: SessionManager.inMemory(),
+  settingsManager: SettingsManager.inMemory(),
+});
+
+// Run prompts
+facade.subscribe((event) => {
+  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+await facade.prompt("Hello");
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `modelRuntime` | Runtime using `agentDir/auth.json` and `models.json` | Canonical model and authentication runtime |
+| `cwd` | `process.cwd()` | Working directory |
+| `agentDir` | `~/.agent-forge/agent` | Config directory |
+| `model` | From settings/first available | Model to use |
+| `thinkingLevel` | From settings/"off" | off, low, medium, high |
+| `tools` | `["read", "bash", "edit", "write"]` built-ins | Allowlist tool names across built-in, extension, and custom tools |
+| `customTools` | `[]` | Additional tool definitions |
+| `resourceLoader` | DefaultResourceLoader | Resource loader for extensions, skills, prompts, themes, and context files |
+| `sessionManager` | `SessionManager.create(cwd)` | Persistence |
+| `settingsManager` | `SettingsManager.create(cwd, agentDir)` | Settings overrides |
+
+## Events
+
+```typescript
+facade.subscribe((event) => {
+  switch (event.type) {
+    case "message_update":
+      if (event.assistantMessageEvent.type === "text_delta") {
+        process.stdout.write(event.assistantMessageEvent.delta);
+      }
+      break;
+    case "tool_execution_start":
+      console.log(`Tool: ${event.toolName}`);
+      break;
+    case "tool_execution_end":
+      console.log(`Result: ${event.result}`);
+      break;
+    case "agent_settled":
+      console.log("Done");
+      break;
+  }
+});
+```

package/package.json

@@ -0,0 +1,111 @@
+{
+	"name": "@ai-agent-forge/agent-forge",
+	"version": "0.85.0",
+	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
+	"type": "module",
+	"agentForgeConfig": {
+		"name": "agent-forge",
+		"configDir": ".agent-forge"
+	},
+	"bin": {
+		"agent-forge": "dist/bundle/cli.js"
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./rpc-entry": {
+			"import": "./dist/bundle/rpc-entry.js"
+		},
+		"./testing": {
+			"types": "./dist/testing/index.d.ts",
+			"import": "./dist/testing/index.js"
+		},
+		"./client": {
+			"types": "./dist/client/index.d.ts",
+			"import": "./dist/client/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"docs",
+		"examples",
+		"containerization.md",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"clean": "shx rm -rf dist",
+		"build": "npm run build:unbundled && node ../../scripts/build-agent-forge-bundle.mjs",
+		"build:unbundled": "tsgo -p tsconfig.build.json && shx chmod +x dist/cli.js dist/rpc-entry.js && npm run copy-assets",
+		"build:binary": "npm --prefix ../tui run build && npm --prefix ../telemetry run build && npm --prefix ../ai run build && npm --prefix ../agent run build && npm --prefix ../protocol run build && npm --prefix ../client run build && npm --prefix ../plugin-sdk run build && npm run build && bun build --compile --no-compile-autoload-bunfig ./src/bun/cli.ts ./src/utils/image-resize-worker.ts --outfile dist/agent-forge && npm run copy-binary-assets",
+		"copy-assets": "shx mkdir -p dist/modes/interactive/theme && shx cp src/modes/interactive/theme/*.json dist/modes/interactive/theme/ && shx mkdir -p dist/modes/interactive/assets && shx cp src/modes/interactive/assets/*.png dist/modes/interactive/assets/ && shx mkdir -p dist/core/export-html/vendor && shx cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/core/export-html/ && shx cp src/core/export-html/vendor/*.js dist/core/export-html/vendor/",
+		"copy-binary-assets": "shx cp package.json dist/ && shx cp README.md dist/ && shx cp CHANGELOG.md dist/ && shx mkdir -p dist/theme && shx cp src/modes/interactive/theme/*.json dist/theme/ && shx mkdir -p dist/assets && shx cp src/modes/interactive/assets/*.png dist/assets/ && shx mkdir -p dist/export-html/vendor && shx cp src/core/export-html/template.html dist/export-html/ && shx cp src/core/export-html/vendor/*.js dist/export-html/vendor/ && shx cp -r docs dist/ && shx cp -r examples dist/ && shx cp ../../node_modules/@silvia-odwyer/photon-node/photon_rs_bg.wasm dist/",
+		"test": "vitest --run",
+		"shrinkwrap": "node ../../scripts/generate-agent-forge-shrinkwrap.mjs",
+		"prepublishOnly": "npm run clean && npm run build && npm run shrinkwrap",
+		"test:coverage": "vitest --run --coverage",
+		"test:plugin-coverage": "vitest --run --config vitest.plugin-coverage.config.ts --coverage",
+		"test:plugin-adapter-coverage": "vitest --run --config vitest.plugin-adapter-coverage.config.ts --coverage",
+		"test:plugin-manager-coverage": "vitest --run --config vitest.plugin-manager-coverage.config.ts --coverage"
+	},
+	"dependencies": {
+		"@silvia-odwyer/photon-node": "0.3.4",
+		"chalk": "5.6.2",
+		"cross-spawn": "7.0.6",
+		"diff": "8.0.4",
+		"grok-mermaid": "0.2.2",
+		"highlight.js": "10.7.3",
+		"hosted-git-info": "9.0.3",
+		"ignore": "7.0.8",
+		"jiti": "2.7.0",
+		"minimatch": "10.2.5",
+		"proper-lockfile": "4.1.2",
+		"semver": "7.8.0",
+		"typebox": "1.3.27",
+		"undici": "8.9.0",
+		"yaml": "2.9.0"
+	},
+	"overrides": {
+		"protobufjs": "7.6.6"
+	},
+	"optionalDependencies": {
+		"@mariozechner/clipboard": "0.3.9"
+	},
+	"devDependencies": {
+		"@types/cross-spawn": "6.0.6",
+		"@types/hosted-git-info": "3.0.5",
+		"@types/node": "22.19.19",
+		"@types/proper-lockfile": "4.1.4",
+		"@types/semver": "7.7.1",
+		"@vitest/coverage-v8": "4.1.9",
+		"shx": "0.4.0",
+		"typescript": "5.9.3",
+		"vitest": "4.1.9",
+		"ws": "8.21.0"
+	},
+	"keywords": [
+		"agent-forge",
+		"ai",
+		"llm",
+		"cli",
+		"tui",
+		"agent"
+	],
+	"author": "Agent Forge contributors",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/agent-forge/agent-forge.git",
+		"directory": "packages/agent-forge"
+	},
+	"bugs": {
+		"url": "https://github.com/agent-forge/agent-forge/issues"
+	},
+	"homepage": "https://github.com/agent-forge/agent-forge#readme",
+	"engines": {
+		"node": ">=22.19.0"
+	}
+}