@hyperspaceng/neural-coding-agent 0.60.0

package/examples/sdk/README.md

@@ -0,0 +1,144 @@
+# SDK Examples
+
+Programmatic usage of pi-coding-agent via `createAgentSession()`.
+
+## 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 tools, custom tools |
+| `06-extensions.ts` | Logging, blocking, result modification |
+| `07-context-files.ts` | AGENTS.md context files |
+| `08-slash-commands.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 |
+
+## Running
+
+```bash
+cd packages/coding-agent
+npx tsx examples/sdk/01-minimal.ts
+```
+
+## Quick Reference
+
+```typescript
+import { getModel } from "@mariozechner/pi-ai";
+import {
+  AuthStorage,
+  createAgentSession,
+  DefaultResourceLoader,
+  ModelRegistry,
+  SessionManager,
+  SettingsManager,
+  codingTools,
+  readOnlyTools,
+  readTool, bashTool, editTool, writeTool,
+} from "@mariozechner/pi-coding-agent";
+
+// Auth and models setup
+const authStorage = AuthStorage.create();
+const modelRegistry = new ModelRegistry(authStorage);
+
+// Minimal
+const { session } = await createAgentSession({ authStorage, modelRegistry });
+
+// Custom model
+const model = getModel("anthropic", "claude-opus-4-5");
+const { session } = await createAgentSession({ model, thinkingLevel: "high", authStorage, modelRegistry });
+
+// Modify prompt
+const loader = new DefaultResourceLoader({
+  systemPromptOverride: (base) => `${base}\n\nBe concise.`,
+});
+await loader.reload();
+const { session } = await createAgentSession({ resourceLoader: loader, authStorage, modelRegistry });
+
+// Read-only
+const { session } = await createAgentSession({ tools: readOnlyTools, authStorage, modelRegistry });
+
+// In-memory
+const { session } = await createAgentSession({
+  sessionManager: SessionManager.inMemory(),
+  authStorage,
+  modelRegistry,
+});
+
+// Full control
+const customAuth = AuthStorage.create("/my/app/auth.json");
+customAuth.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
+const customRegistry = new ModelRegistry(customAuth);
+
+const resourceLoader = new DefaultResourceLoader({
+  systemPromptOverride: () => "You are helpful.",
+  extensionFactories: [myExtension],
+  skillsOverride: () => ({ skills: [], diagnostics: [] }),
+  agentsFilesOverride: () => ({ agentsFiles: [] }),
+  promptsOverride: () => ({ prompts: [], diagnostics: [] }),
+});
+await resourceLoader.reload();
+
+const { session } = await createAgentSession({
+  model,
+  authStorage: customAuth,
+  modelRegistry: customRegistry,
+  resourceLoader,
+  tools: [readTool, bashTool],
+  customTools: [{ tool: myTool }],
+  sessionManager: SessionManager.inMemory(),
+  settingsManager: SettingsManager.inMemory(),
+});
+
+// Run prompts
+session.subscribe((event) => {
+  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+await session.prompt("Hello");
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `authStorage` | `AuthStorage.create()` | Credential storage |
+| `modelRegistry` | `new ModelRegistry(authStorage)` | Model registry |
+| `cwd` | `process.cwd()` | Working directory |
+| `agentDir` | `~/.pi/agent` | Config directory |
+| `model` | From settings/first available | Model to use |
+| `thinkingLevel` | From settings/"off" | off, low, medium, high |
+| `tools` | `codingTools` | Built-in tools |
+| `customTools` | `[]` | Additional tool definitions |
+| `resourceLoader` | DefaultResourceLoader | Resource loader for extensions, skills, prompts, themes |
+| `sessionManager` | `SessionManager.create(cwd)` | Persistence |
+| `settingsManager` | `SettingsManager.create(cwd, agentDir)` | Settings overrides |
+
+## Events
+
+```typescript
+session.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_end":
+      console.log("Done");
+      break;
+  }
+});
+```

package/package.json

@@ -0,0 +1,99 @@
+{
+	"name": "@hyperspaceng/neural-coding-agent",
+	"version": "0.60.0",
+	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
+	"type": "module",
+	"piConfig": {
+		"name": "neural",
+		"configDir": ".pi"
+	},
+	"bin": {
+		"neural": "dist/cli.js"
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./hooks": {
+			"types": "./dist/core/hooks/index.d.ts",
+			"import": "./dist/core/hooks/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"docs",
+		"examples",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"clean": "shx rm -rf dist",
+		"dev": "tsgo -p tsconfig.build.json --watch --preserveWatchOutput",
+		"build": "tsgo -p tsconfig.build.json && shx chmod +x dist/cli.js && npm run copy-assets",
+		"build:binary": "npm --prefix ../tui run build && npm --prefix ../ai run build && npm --prefix ../agent run build && npm run build && bun build --compile ./dist/bun/cli.js --outfile dist/pi && 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/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/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",
+		"prepublishOnly": "npm run clean && npm run build"
+	},
+	"dependencies": {
+		"@mariozechner/jiti": "^2.6.2",
+		"@hyperspaceng/neural-agent-core": "^0.60.0",
+		"@hyperspaceng/neural-ai": "^0.60.0",
+		"@hyperspaceng/neural-tui": "^0.60.0",
+		"@silvia-odwyer/photon-node": "^0.3.4",
+		"chalk": "^5.5.0",
+		"cli-highlight": "^2.1.11",
+		"diff": "^8.0.2",
+		"extract-zip": "^2.0.1",
+		"file-type": "^21.1.1",
+		"glob": "^13.0.1",
+		"hosted-git-info": "^9.0.2",
+		"ignore": "^7.0.5",
+		"marked": "^15.0.12",
+		"minimatch": "^10.2.3",
+		"proper-lockfile": "^4.1.2",
+		"strip-ansi": "^7.1.0",
+		"undici": "^7.19.1",
+		"yaml": "^2.8.2"
+	},
+	"overrides": {
+		"rimraf": "6.1.2",
+		"gaxios": {
+			"rimraf": "6.1.2"
+		}
+	},
+	"optionalDependencies": {
+		"@hyperspaceng/neural-clipboard": "^0.3.2"
+	},
+	"devDependencies": {
+		"@types/diff": "^7.0.2",
+		"@types/hosted-git-info": "^3.0.5",
+		"@types/ms": "^2.1.0",
+		"@types/node": "^24.3.0",
+		"@types/proper-lockfile": "^4.1.4",
+		"shx": "^0.4.0",
+		"typescript": "^5.7.3",
+		"vitest": "^3.2.4"
+	},
+	"keywords": [
+		"coding-agent",
+		"ai",
+		"llm",
+		"cli",
+		"tui",
+		"agent"
+	],
+	"author": "Hyperspace Technologies <hyperspace@hyperspace.ng>",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/DrOlu/pi-mono.git",
+		"directory": "packages/coding-agent"
+	},
+	"engines": {
+		"node": ">=20.6.0"
+	}
+}