@ai-agent-forge/agent-forge 0.85.0

package/examples/sdk/03-custom-prompt.ts

@@ -0,0 +1,70 @@
+/**
+ * Custom System Prompt
+ *
+ * Shows how to replace or modify the default system prompt.
+ */
+
+import { createStableAgentSession, DefaultResourceLoader, getAgentDir, SessionManager } from "@agent-forge/agent-forge";
+
+const cwd = process.cwd();
+const agentDir = getAgentDir();
+
+// Option 1: Replace prompt entirely
+const loader1 = new DefaultResourceLoader({
+	cwd,
+	agentDir,
+	systemPromptOverride: () => `You are a helpful assistant that speaks like a pirate.
+Always end responses with "Arrr!"`,
+	// Needed to avoid DefaultResourceLoader appending APPEND_SYSTEM.md from ~/.agent-forge/agent or <cwd>/.agent-forge.
+	appendSystemPromptOverride: () => [],
+});
+await loader1.reload();
+
+const { facade: facade1 } = await createStableAgentSession({
+	resourceLoader: loader1,
+	sessionManager: SessionManager.inMemory(),
+});
+
+try {
+	facade1.subscribe((event) => {
+		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+			process.stdout.write(event.assistantMessageEvent.delta);
+		}
+	});
+
+	console.log("=== Replace prompt ===");
+	await facade1.prompt("What is 2 + 2?");
+	console.log("\n");
+} finally {
+	facade1.dispose();
+}
+
+// Option 2: Append instructions to the default prompt
+const loader2 = new DefaultResourceLoader({
+	cwd,
+	agentDir,
+	appendSystemPromptOverride: (base) => [
+		...base,
+		"## Additional Instructions\n- Always be concise\n- Use bullet points when listing things",
+	],
+});
+await loader2.reload();
+
+const { facade: facade2 } = await createStableAgentSession({
+	resourceLoader: loader2,
+	sessionManager: SessionManager.inMemory(),
+});
+
+try {
+	facade2.subscribe((event) => {
+		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+			process.stdout.write(event.assistantMessageEvent.delta);
+		}
+	});
+
+	console.log("=== Modify prompt ===");
+	await facade2.prompt("List 3 benefits of TypeScript.");
+	console.log();
+} finally {
+	facade2.dispose();
+}

package/examples/sdk/04-skills.ts

@@ -0,0 +1,55 @@
+/**
+ * Skills Configuration
+ *
+ * Skills provide specialized instructions loaded into the system prompt.
+ * Discover, filter, merge, or replace them.
+ */
+
+import {
+	createStableAgentSession,
+	createSyntheticSourceInfo,
+	DefaultResourceLoader,
+	getAgentDir,
+	SessionManager,
+	type Skill,
+} from "@agent-forge/agent-forge";
+
+// Or define custom skills inline
+const customSkill: Skill = {
+	name: "my-skill",
+	description: "Custom project instructions",
+	filePath: "/virtual/SKILL.md",
+	baseDir: "/virtual",
+	sourceInfo: createSyntheticSourceInfo("/virtual/SKILL.md", { source: "sdk" }),
+	disableModelInvocation: false,
+};
+
+const loader = new DefaultResourceLoader({
+	cwd: process.cwd(),
+	agentDir: getAgentDir(),
+	skillsOverride: (current) => {
+		const filteredSkills = current.skills.filter((s) => s.name.includes("browser") || s.name.includes("search"));
+		return {
+			skills: [...filteredSkills, customSkill],
+			diagnostics: current.diagnostics,
+		};
+	},
+});
+await loader.reload();
+
+// Discover all skills from cwd/.agent-forge/skills, ~/.agent-forge/agent/skills, etc.
+const { skills: allSkills, diagnostics } = loader.getSkills();
+console.log(
+	"Discovered skills:",
+	allSkills.map((s) => s.name),
+);
+if (diagnostics.length > 0) {
+	console.log("Warnings:", diagnostics);
+}
+
+const { facade } = await createStableAgentSession({
+	resourceLoader: loader,
+	sessionManager: SessionManager.inMemory(),
+});
+console.log("Session created with filtered skills");
+facade.dispose();

package/examples/sdk/05-tools.ts

@@ -0,0 +1,48 @@
+/**
+ * Tools Configuration
+ *
+ * Use tool names to choose which built-in tools are enabled.
+ *
+ * Tool names are matched against all available tools. If you use a custom `cwd`,
+ * createStableAgentSession() applies that cwd when it builds the actual built-in tools.
+ *
+ * For custom tools, see 06-extensions.ts - custom tools are registered via the
+ * extensions system using pi.registerTool().
+ */
+
+import { createStableAgentSession, SessionManager } from "@agent-forge/agent-forge";
+
+// Read-only mode (no edit/write)
+const { facade: readOnlyFacade } = await createStableAgentSession({
+	tools: ["read", "grep", "find", "ls"],
+	sessionManager: SessionManager.inMemory(),
+});
+console.log("Read-only session created");
+readOnlyFacade.dispose();
+
+// Custom tool selection
+const { facade: customToolsFacade } = await createStableAgentSession({
+	tools: ["read", "bash", "grep"],
+	sessionManager: SessionManager.inMemory(),
+});
+console.log("Custom tools session created");
+customToolsFacade.dispose();
+
+// With custom cwd
+const customCwd = "/path/to/project";
+const { facade: customCwdFacade } = await createStableAgentSession({
+	cwd: customCwd,
+	tools: ["read", "bash", "edit", "write"],
+	sessionManager: SessionManager.inMemory(customCwd),
+});
+console.log("Custom cwd session created");
+customCwdFacade.dispose();
+
+// Or pick specific tools for custom cwd
+const { facade: specificToolsFacade } = await createStableAgentSession({
+	cwd: customCwd,
+	tools: ["read", "bash", "grep"],
+	sessionManager: SessionManager.inMemory(customCwd),
+});
+console.log("Specific tools with custom cwd session created");
+specificToolsFacade.dispose();

package/examples/sdk/07-context-files.ts

@@ -0,0 +1,42 @@
+/**
+ * Context Files (AGENTS.md)
+ *
+ * Context files provide project-specific instructions loaded into the system prompt.
+ */
+
+import { createStableAgentSession, DefaultResourceLoader, getAgentDir, SessionManager } from "@agent-forge/agent-forge";
+
+// Disable context files entirely by returning an empty list in agentsFilesOverride.
+const loader = new DefaultResourceLoader({
+	cwd: process.cwd(),
+	agentDir: getAgentDir(),
+	agentsFilesOverride: (current) => ({
+		agentsFiles: [
+			...current.agentsFiles,
+			{
+				path: "/virtual/AGENTS.md",
+				content: `# Project Guidelines
+
+## Code Style
+- Use TypeScript strict mode
+- No any types
+- Prefer const over let`,
+			},
+		],
+	}),
+});
+await loader.reload();
+
+// Discover AGENTS.md files walking up from cwd
+const discovered = loader.getAgentsFiles().agentsFiles;
+console.log("Discovered context files:");
+for (const file of discovered) {
+	console.log(`  - ${file.path} (${file.content.length} chars)`);
+}
+
+const { facade } = await createStableAgentSession({
+	resourceLoader: loader,
+	sessionManager: SessionManager.inMemory(),
+});
+console.log(`Session created with ${discovered.length + 1} context files`);
+facade.dispose();

package/examples/sdk/08-prompt-templates.ts

@@ -0,0 +1,51 @@
+/**
+ * Prompt Templates
+ *
+ * File-based templates that inject content when invoked with /templatename.
+ */
+
+import {
+	createStableAgentSession,
+	createSyntheticSourceInfo,
+	DefaultResourceLoader,
+	getAgentDir,
+	type PromptTemplate,
+	SessionManager,
+} from "@agent-forge/agent-forge";
+
+// Define custom templates
+const deployTemplate: PromptTemplate = {
+	name: "deploy",
+	description: "Deploy the application",
+	filePath: "/virtual/prompts/deploy.md",
+	sourceInfo: createSyntheticSourceInfo("/virtual/prompts/deploy.md", { source: "sdk" }),
+	content: `# Deploy Instructions
+
+1. Build: npm run build
+2. Test: npm test
+3. Deploy: npm run deploy`,
+};
+
+const loader = new DefaultResourceLoader({
+	cwd: process.cwd(),
+	agentDir: getAgentDir(),
+	promptsOverride: (current) => ({
+		prompts: [...current.prompts, deployTemplate],
+		diagnostics: current.diagnostics,
+	}),
+});
+await loader.reload();
+
+// Discover templates from cwd/.agent-forge/prompts/ and ~/.agent-forge/agent/prompts/
+const discovered = loader.getPrompts().prompts;
+console.log("Discovered prompt templates:");
+for (const template of discovered) {
+	console.log(`  /${template.name}: ${template.description}`);
+}
+
+const { facade } = await createStableAgentSession({
+	resourceLoader: loader,
+	sessionManager: SessionManager.inMemory(),
+});
+console.log(`Session created with ${discovered.length + 1} prompt templates`);
+facade.dispose();

package/examples/sdk/09-api-keys-and-oauth.ts

@@ -0,0 +1,34 @@
+/**
+ * API Keys and OAuth
+ *
+ * Configure provider auth through ModelRuntime.
+ */
+
+import { createStableAgentSession, ModelRuntime, SessionManager } from "@agent-forge/agent-forge";
+
+const modelRuntime = await ModelRuntime.create();
+const { facade: defaultAuthFacade } = await createStableAgentSession({
+	sessionManager: SessionManager.inMemory(),
+	modelRuntime,
+});
+console.log("Session with default model runtime");
+defaultAuthFacade.dispose();
+
+const customRuntime = await ModelRuntime.create({
+	authPath: "/tmp/my-app/auth.json",
+	modelsPath: "/tmp/my-app/models.json",
+});
+const { facade: customAuthFacade } = await createStableAgentSession({
+	sessionManager: SessionManager.inMemory(),
+	modelRuntime: customRuntime,
+});
+console.log("Session with custom auth and models locations");
+customAuthFacade.dispose();
+
+await modelRuntime.setRuntimeApiKey("anthropic", "sk-my-temp-key");
+const { facade: runtimeKeyFacade } = await createStableAgentSession({
+	sessionManager: SessionManager.inMemory(),
+	modelRuntime,
+});
+console.log("Session with runtime API key override");
+runtimeKeyFacade.dispose();

package/examples/sdk/10-settings.ts

@@ -0,0 +1,53 @@
+/**
+ * Settings Configuration
+ *
+ * Override settings using SettingsManager.
+ */
+
+import { createStableAgentSession, SessionManager, SettingsManager } from "@agent-forge/agent-forge";
+
+const cwd = process.cwd();
+
+// Load current settings (merged global + project)
+const settingsManagerFromDisk = SettingsManager.create(cwd);
+console.log("Current settings:", JSON.stringify(settingsManagerFromDisk.getGlobalSettings(), null, 2));
+
+// Override specific settings
+const settingsManager = SettingsManager.create(cwd);
+settingsManager.applyOverrides({
+	compaction: { enabled: false },
+	retry: { enabled: true, maxRetries: 5, baseDelayMs: 1000 },
+});
+
+const { facade: customSettingsFacade } = await createStableAgentSession({
+	settingsManager,
+	sessionManager: SessionManager.inMemory(),
+});
+console.log("Session created with custom settings");
+customSettingsFacade.dispose();
+
+// Setters update memory immediately and queue persistence writes.
+// Call flush() when you need a durability boundary.
+settingsManager.setDefaultThinkingLevel("low");
+await settingsManager.flush();
+
+// Surface settings I/O errors at the app layer.
+const settingsErrors = settingsManager.drainErrors();
+if (settingsErrors.length > 0) {
+	for (const { scope, error } of settingsErrors) {
+		console.warn(`Warning (${scope} settings): ${error.message}`);
+	}
+}
+
+// For testing without file I/O:
+const inMemorySettings = SettingsManager.inMemory({
+	compaction: { enabled: false },
+	retry: { enabled: false },
+});
+
+const { facade: testFacade } = await createStableAgentSession({
+	settingsManager: inMemorySettings,
+	sessionManager: SessionManager.inMemory(),
+});
+console.log("Test session created with in-memory settings");
+testFacade.dispose();

package/examples/sdk/11-sessions.ts

@@ -0,0 +1,52 @@
+/**
+ * Session Management
+ *
+ * Control session persistence: in-memory, new file, continue, or open specific.
+ */
+
+import { createStableAgentSession, SessionManager } from "@agent-forge/agent-forge";
+
+// In-memory (no persistence)
+const { facade: inMemoryFacade } = await createStableAgentSession({
+	sessionManager: SessionManager.inMemory(),
+});
+console.log("In-memory session:", inMemoryFacade.getSessionFile() ?? "(none)");
+inMemoryFacade.dispose();
+
+// New persistent session
+const { facade: newSessionFacade } = await createStableAgentSession({
+	sessionManager: SessionManager.create(process.cwd()),
+});
+console.log("New session file:", newSessionFacade.getSessionFile());
+newSessionFacade.dispose();
+
+// Continue most recent session (or create new if none)
+const { facade: continuedFacade, modelFallbackMessage } = await createStableAgentSession({
+	sessionManager: SessionManager.continueRecent(process.cwd()),
+});
+if (modelFallbackMessage) console.log("Note:", modelFallbackMessage);
+console.log("Continued session:", continuedFacade.getSessionFile());
+continuedFacade.dispose();
+
+// List and open specific session
+const sessions = await SessionManager.list(process.cwd());
+console.log(`\nFound ${sessions.length} sessions:`);
+for (const info of sessions.slice(0, 3)) {
+	console.log(`  ${info.id.slice(0, 8)}... - "${info.firstMessage.slice(0, 30)}..."`);
+}
+
+if (sessions.length > 0) {
+	const { facade: openedFacade } = await createStableAgentSession({
+		sessionManager: SessionManager.open(sessions[0].path),
+	});
+	console.log(`\nOpened: ${openedFacade.getSessionId()}`);
+	openedFacade.dispose();
+}
+
+// Custom session directory (no cwd encoding)
+// const customDir = "/path/to/my-sessions";
+// const { facade } = await createStableAgentSession({
+//   sessionManager: SessionManager.create(process.cwd(), customDir),
+// });
+// SessionManager.list(process.cwd(), customDir);
+// SessionManager.continueRecent(process.cwd(), customDir);

package/examples/sdk/12-full-control.ts

@@ -0,0 +1,72 @@
+/**
+ * Full Control
+ *
+ * Replace everything - no discovery, explicit configuration.
+ */
+
+import {
+	createStableAgentSession,
+	ModelRuntime,
+	type ResourceLoader,
+	SessionManager,
+	SettingsManager,
+} from "@agent-forge/agent-forge";
+import { getModel } from "@agent-forge/ai/compat";
+
+const modelRuntime = await ModelRuntime.create({
+	authPath: "/tmp/my-agent/auth.json",
+	modelsPath: "/tmp/my-agent/models.json",
+});
+if (process.env.MY_ANTHROPIC_KEY) {
+	await modelRuntime.setRuntimeApiKey("anthropic", process.env.MY_ANTHROPIC_KEY);
+}
+
+const model = getModel("anthropic", "claude-sonnet-4-5");
+if (!model) throw new Error("Model not found");
+
+// In-memory settings with overrides
+const settingsManager = SettingsManager.inMemory({
+	compaction: { enabled: false },
+	retry: { enabled: true, maxRetries: 2 },
+});
+
+const cwd = process.cwd();
+
+const resourceLoader: ResourceLoader = {
+	getSkills: () => ({ skills: [], diagnostics: [] }),
+	getPrompts: () => ({ prompts: [], diagnostics: [] }),
+	getThemes: () => ({ themes: [], diagnostics: [] }),
+	getAgentsFiles: () => ({ agentsFiles: [] }),
+	getSystemPrompt: () => `You are a minimal assistant.
+Available: read, bash. Be concise.`,
+	getSystemPromptSource: () => undefined,
+	getAppendSystemPrompt: () => [],
+	getAppendSystemPromptSources: () => [],
+	extendResources: () => {},
+	reload: async () => {},
+};
+
+const { facade } = await createStableAgentSession({
+	cwd,
+	agentDir: "/tmp/my-agent",
+	model,
+	thinkingLevel: "off",
+	modelRuntime,
+	resourceLoader,
+	tools: ["read", "bash"],
+	sessionManager: SessionManager.inMemory(cwd),
+	settingsManager,
+});
+
+try {
+	facade.subscribe((event) => {
+		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+			process.stdout.write(event.assistantMessageEvent.delta);
+		}
+	});
+
+	await facade.prompt("List files in the current directory.");
+	console.log();
+} finally {
+	facade.dispose();
+}

package/examples/sdk/13-session-runtime.ts

@@ -0,0 +1,71 @@
+/**
+ * Session runtime
+ *
+ * Use the stable runtime entry when you need to replace the active session,
+ * for example for new-session, resume, fork, or import flows.
+ *
+ * The important pattern is: after the runtime replaces the active session,
+ * re-read the current session's facade (`runtimeFacade.getSessionFacade()`) and
+ * re-subscribe; the accessor re-projects the runtime's current session, so there
+ * is no raw session reference to rebind by hand.
+ */
+
+import {
+	type CreateAgentSessionRuntimeFactory,
+	createAgentSessionFromServices,
+	createAgentSessionServices,
+	createStableAgentSessionRuntime,
+	getAgentDir,
+	SessionManager,
+} from "@agent-forge/agent-forge";
+
+const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
+	const services = await createAgentSessionServices({ cwd });
+	return {
+		...(await createAgentSessionFromServices({
+			services,
+			sessionManager,
+			sessionStartEvent,
+		})),
+		services,
+		diagnostics: services.diagnostics,
+	};
+};
+const { runtimeFacade } = await createStableAgentSessionRuntime(createRuntime, {
+	cwd: process.cwd(),
+	agentDir: getAgentDir(),
+	sessionManager: SessionManager.create(process.cwd()),
+});
+
+let unsubscribe: (() => void) | undefined;
+
+function bindSession() {
+	unsubscribe?.();
+	// Extension binding is host assembly: a host wires it through the runtime's
+	// rebind callback (`setRebindSession`) it registers itself. The stable surface
+	// has no such call (bindExtensions is a permanent carve-out, D-054).
+	const facade = runtimeFacade.getSessionFacade();
+	unsubscribe = facade.subscribe((event) => {
+		if (event.type === "queue_update") {
+			console.log("Queued:", event.steering.length + event.followUp.length);
+		}
+	});
+	return facade;
+}
+
+let facade = bindSession();
+const originalSessionFile = facade.getSessionFile();
+console.log("Initial session:", originalSessionFile);
+
+await runtimeFacade.newSession();
+facade = bindSession();
+console.log("After newSession():", facade.getSessionFile());
+
+if (originalSessionFile) {
+	await runtimeFacade.switchSession(originalSessionFile);
+	facade = bindSession();
+	console.log("After switchSession():", facade.getSessionFile());
+}
+
+unsubscribe?.();
+await runtimeFacade.dispose();

package/examples/sdk/14-custom-session-storage.ts

@@ -0,0 +1,132 @@
+/**
+ * Custom Session Storage
+ *
+ * Every session-record read/write flows through one injectable seam:
+ * `SessionStorageProvider`. The default implementation is the local JSONL
+ * file protocol (`FileSessionStorageProvider`); the seam is public and
+ * first-party code uses the exact same path a third party would — inject a
+ * provider and your implementation carries the session history instead.
+ *
+ * This example wraps the file provider with a mirroring one: every mutating
+ * call (create/append/rewrite/truncate/remove) is echoed to the console, the
+ * way you would mirror records to an audit log or push them to your own
+ * storage. Reads pass through untouched.
+ *
+ * Records flush on the first assistant message, so the demo runs one
+ * deterministic turn against the faux provider (no network, no API key).
+ *
+ * The provider rides `SessionManager.create(cwd, sessionsDir, options,
+ * storage)`; hosts driving sessions through a server assembly inject it via
+ * `FileSessionSourceOptions.storage` instead — same interface, same contract.
+ */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	createStableAgentSession,
+	type FileEntry,
+	FileSessionStorageProvider,
+	SessionManager,
+	type SessionStorageProvider,
+} from "@agent-forge/agent-forge";
+import { fauxAssistantMessage, type Model } from "@agent-forge/ai";
+import { registerFauxProvider, streamSimple } from "@agent-forge/ai/compat";
+
+class MirroringSessionStorage implements SessionStorageProvider {
+	private readonly inner = new FileSessionStorageProvider();
+
+	ensureDir(dir: string): void {
+		this.inner.ensureDir(dir);
+	}
+
+	exists(path: string): boolean {
+		return this.inner.exists(path);
+	}
+
+	size(path: string): number {
+		return this.inner.size(path);
+	}
+
+	loadEntries(path: string): FileEntry[] {
+		return this.inner.loadEntries(path);
+	}
+
+	readHeader(path: string) {
+		return this.inner.readHeader(path);
+	}
+
+	createExclusive(path: string, entries: readonly FileEntry[]): void {
+		console.log(`[storage] create ${path} (${entries.length} entries, header first)`);
+		this.inner.createExclusive(path, entries);
+	}
+
+	append(path: string, entry: FileEntry): void {
+		console.log(`[storage] append ${path} -> ${entry.type}`);
+		this.inner.append(path, entry);
+	}
+
+	rewrite(path: string, entries: readonly FileEntry[]): void {
+		console.log(`[storage] rewrite ${path} (${entries.length} entries)`);
+		this.inner.rewrite(path, entries);
+	}
+
+	truncate(path: string, size: number): void {
+		console.log(`[storage] truncate ${path} back to ${size} bytes`);
+		this.inner.truncate(path, size);
+	}
+
+	remove(path: string): void {
+		console.log(`[storage] remove ${path}`);
+		this.inner.remove(path);
+	}
+
+	listSessionFiles(dir: string): string[] {
+		return this.inner.listSessionFiles(dir);
+	}
+
+	modifiedTime(path: string): Date {
+		return this.inner.modifiedTime(path);
+	}
+}
+
+const faux = registerFauxProvider({
+	models: [
+		{
+			id: "storage-demo-model",
+			name: "Storage Demo",
+			reasoning: false,
+			input: ["text"],
+			contextWindow: 32_000,
+			maxTokens: 4_096,
+		},
+	],
+});
+faux.setResponses([fauxAssistantMessage("storage ack")]);
+const model: Model<string> = faux.getModel();
+
+const workDir = mkdtempSync(join(tmpdir(), "storage-demo-"));
+try {
+	const sessionsDir = join(workDir, "sessions");
+	const storage = new MirroringSessionStorage();
+
+	// The provider rides the session manager; every record write the session
+	// makes lands in it — the header included, on the first flush.
+	const sessionManager = SessionManager.create(workDir, sessionsDir, undefined, storage);
+	const { facade, sessionAPI } = await createStableAgentSession({
+		sessionManager,
+		streamFn: streamSimple,
+		model,
+	});
+
+	// The turn's user + assistant messages flush the session file through the
+	// provider; the custom entry afterwards appends through it too.
+	await facade.prompt("hello through the injected provider");
+	sessionAPI.appendEntry("storage-demo", { note: "written through the injected provider" });
+	console.log(`[storage] session id: ${sessionAPI.getSessionId()}`);
+
+	await facade.dispose();
+} finally {
+	faux.unregister();
+	rmSync(workDir, { recursive: true, force: true });
+}