@korallis/k-pi 0.1.0

package/examples/sdk/README.md

@@ -0,0 +1,140 @@
+# SDK Examples
+
+Programmatic usage of pi-coding-agent via `createAgentSession()` and `createAgentSessionRuntime()`.
+
+The runtime example 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.
+
+## 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 |
+| `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 |
+| `13-session-runtime.ts` | Manage runtime-backed session replacement |
+
+## Running
+
+```bash
+cd packages/coding-agent
+npx tsx examples/sdk/01-minimal.ts
+```
+
+## Quick Reference
+
+```typescript
+import { getModel } from "@earendil-works/pi-ai";
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  ModelRuntime,
+  SessionManager,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+
+const modelRuntime = await ModelRuntime.create();
+
+// Minimal
+const { session } = await createAgentSession({ modelRuntime });
+
+// Custom model
+const model = getModel("anthropic", "claude-opus-4-5");
+const { session } = await createAgentSession({ model, thinkingLevel: "high", modelRuntime });
+
+// Modify prompt
+const loader = new DefaultResourceLoader({
+  systemPromptOverride: (base) => `${base}\n\nBe concise.`,
+});
+await loader.reload();
+const { session } = await createAgentSession({ resourceLoader: loader, modelRuntime });
+
+// Read-only
+const { session } = await createAgentSession({ tools: ["read", "grep", "find", "ls"], modelRuntime });
+
+// In-memory
+const { session } = await createAgentSession({
+  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 { session } = await createAgentSession({
+  model,
+  modelRuntime: customRuntime,
+  resourceLoader,
+  tools: ["read", "bash", "my_tool"],
+  customTools: [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 |
+|--------|---------|-------------|
+| `modelRuntime` | Runtime using `agentDir/auth.json` and `models.json` | Canonical model and authentication runtime |
+| `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` | `["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
+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_settled":
+      console.log("Done");
+      break;
+  }
+});
+```

package/package.json

@@ -0,0 +1,55 @@
+{
+	"name": "@korallis/k-pi",
+	"version": "0.1.0",
+	"description": "K-π coding agent harness: graph-engineered coding loop, tools, and session management",
+	"license": "MIT",
+	"type": "module",
+	"piConfig": {
+		"name": "kpi",
+		"title": "K-π",
+		"configDir": ".kpi"
+	},
+	"bin": {
+		"kpi": "dist/bundle/cli.js",
+		"k-pi": "dist/bundle/cli.js"
+	},
+	"files": [
+		"dist",
+		"docs",
+		"examples",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE",
+		"NOTICE"
+	],
+	"dependencies": {
+		"@silvia-odwyer/photon-node": "0.3.4",
+		"jiti": "2.7.0"
+	},
+	"optionalDependencies": {
+		"@mariozechner/clipboard": "0.3.9"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"keywords": [
+		"coding-agent",
+		"ai",
+		"llm",
+		"cli",
+		"tui",
+		"agent"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/korallis/K-pi.git",
+		"directory": "packages/coding-agent"
+	},
+	"homepage": "https://github.com/korallis/K-pi#readme",
+	"bugs": {
+		"url": "https://github.com/korallis/K-pi/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}