pk-agent 0.7.2

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2025 Leon Ho.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,403 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./static/pk-agent-logo-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="./static/pk-agent-logo.png">
+  <img alt="PK Agent Logo" src="./static/pk-agent-logo.png" width="full">
+</picture>
+
+<br/>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/pk-agent"><img alt="Version" src="https://img.shields.io/npm/v/pk-agent?style=flat-square&color=00DC82&label=version"></a>&nbsp;
+  <a href="https://www.npmjs.com/package/pk-agent"><img alt="Downloads" src="https://img.shields.io/npm/dm/pk-agent?style=flat-square&color=00DC82"></a>&nbsp;
+  <a href="https://github.com/pk-agent/pk-agent/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/npm/l/pk-agent?style=flat-square&color=00DC82"></a>
+</p>
+
+<h3 align="center">
+  Build AI agents as simple text files.<br/>
+  No coding required.
+</h3>
+
+<br/>
+
+---
+
+<br/>
+
+## Quickstart
+
+```bash
+git clone git@github.com:kingkillery/pk-agent.git && cd pk-agent && bun install && bun run build && npm pack && npm install -g ./pk-agent-*.tgz
+```
+
+## What is PK-Agent?
+
+PK-Agent lets you create **AI-powered assistants** by writing a short text file - no programming needed. Each file is a set of instructions that tells an AI model what to do, like giving directions to a very capable coworker.
+
+Think of it like a recipe card. The top section lists the ingredients (which AI model to use, what tools it needs). The bottom section is the actual instructions - written in plain English.
+
+Here's a complete agent that generates a daily motivation quote:
+
+```markdown
+---
+model: anthropic:claude-sonnet-4-5
+---
+
+Generate a daily motivation quote with a tech fact.
+Format as JSON with 'quote' and 'fact' fields.
+```
+
+That's it. That file *is* the agent.
+
+<br/>
+
+---
+
+<br/>
+
+## Getting Started
+
+### 1. Install
+
+Open a terminal (Command Prompt, PowerShell, or Terminal) and run:
+
+```
+npm install -g pk-agent
+```
+
+### 2. Connect your AI provider
+
+PK-Agent needs an API key from an AI provider. Think of this like a password that lets PK-Agent talk to the AI on your behalf.
+
+```
+pk-agent auth login
+```
+
+This walks you through connecting to **Anthropic** (Claude), **OpenAI** (GPT), or other providers.
+
+### 3. Create your first agent
+
+Recommended: generate a starter agent file with:
+
+```
+pk-agent create
+```
+
+Or create one manually:
+
+Create a new text file called `my-agent.pk-agent` and paste this in:
+
+```markdown
+---
+model: anthropic:claude-sonnet-4-5
+---
+
+You are a friendly assistant. Greet the user, tell them one
+interesting fact about space, and wish them a great day.
+```
+
+### 4. Run it
+
+```
+pk-agent run my-agent.pk-agent
+```
+
+You'll see the AI respond right in your terminal.
+
+> **Tip:** You can also try agents without installing anything:
+> ```
+> npx pk-agent@latest run my-agent.pk-agent
+> ```
+
+<br/>
+
+---
+
+<br/>
+
+## How Agent Files Work
+
+Every `.pk-agent` file has two parts:
+
+```markdown
+---
+model: anthropic:claude-sonnet-4-5     # Settings (YAML)
+---
+
+You are a helpful research assistant.  # Instructions (Markdown)
+Summarize the latest news about AI
+and format it as bullet points.
+```
+
+| Part | What it does | Required? |
+|---|---|---|
+| **Settings** (between `---` lines) | Tells PK-Agent which AI model to use and what tools to provide | Yes |
+| **Instructions** (below the settings) | Tells the AI what to do, in plain English | Yes |
+
+### Choosing a model
+
+The `model` line tells PK-Agent which AI to use. Some popular options:
+
+| Model | Best for |
+|---|---|
+| `anthropic:claude-sonnet-4-5` | General tasks, writing, analysis |
+| `openai:gpt-5.2` | Broad knowledge, conversation |
+| `openai:gpt-5.2-mini` | Fast, lightweight tasks |
+
+You can switch models by changing one line - your instructions stay the same.
+
+<br/>
+
+---
+
+<br/>
+
+## Real-World Examples
+
+### Summarize a webpage
+
+```markdown
+---
+model: anthropic:claude-sonnet-4-5
+mcpServers:
+  fetch:
+    command: uvx
+    args: [mcp-server-fetch]
+---
+
+Fetch https://news.ycombinator.com and summarize the top 5 stories
+in plain language. Keep each summary to 2 sentences.
+```
+
+### Monitor a website for changes
+
+```markdown
+---
+model: anthropic:claude-sonnet-4-5
+schedule: "0 9 * * *"
+mcpServers:
+  fetch:
+    command: uvx
+    args: [mcp-server-fetch]
+---
+
+Fetch https://example.com/changelog and compare it to yesterday.
+If anything changed, write a summary of what's new.
+```
+
+> The `schedule` line tells PK-Agent to run this automatically. `"0 9 * * *"` means "every day at 9:00 AM."
+
+### Query a database and write a report
+
+```markdown
+---
+model: anthropic:claude-sonnet-4-5
+mcpServers:
+  postgres:
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-postgres"]
+    requiredEnvVars: [DATABASE_URL]
+---
+
+Query the sales table for yesterday's metrics.
+Generate an executive summary with trends and anomalies.
+```
+
+<br/>
+
+---
+
+<br/>
+
+## Adding Capabilities with Tools
+
+Out of the box, an agent can only read and write text. To give it access to the outside world - websites, databases, files, APIs - you connect **tools**.
+
+PK-Agent uses the [Model Context Protocol](https://modelcontextprotocol.io) (MCP) standard, which means hundreds of pre-built tools already exist. You list them in your agent's settings:
+
+```yaml
+mcpServers:
+  fetch:
+    command: uvx
+    args: [mcp-server-fetch]
+```
+
+That single block gives your agent the ability to read any webpage. No code to write, no setup beyond adding those lines.
+
+### Built-in tools
+
+PK-Agent also comes with built-in tools you can enable directly.
+
+#### File access
+
+```yaml
+tools:
+  filesystem:
+    - path: .
+      permissions: [read, write, edit]
+```
+
+#### Shell commands
+
+```yaml
+tools:
+  bash:
+    commands:
+      - "rg -n \"TODO\" ."
+```
+
+#### Window capture
+
+```yaml
+tools:
+  captureWindow: true
+```
+
+<br/>
+
+---
+
+<br/>
+
+## Running Agents
+
+### From a file
+
+```
+pk-agent run my-agent.pk-agent
+```
+
+### With an extra prompt
+
+Append a question or instruction at run time:
+
+```
+pk-agent run my-agent.pk-agent "Focus on stories about robotics"
+```
+
+### On a schedule
+
+Add a `schedule` line to your agent file and it runs automatically:
+
+```yaml
+schedule: "0 9 * * *"      # Every day at 9 AM
+schedule: "*/30 * * * *"   # Every 30 minutes
+```
+
+### As an HTTP server
+
+Start a server and trigger agents over the network:
+
+```
+pk-agent serve
+```
+
+Then from any app, script, or automation tool:
+
+```
+curl -X POST http://localhost:12233/run -d '{"agent": "my-agent"}'
+```
+
+<br/>
+
+---
+
+<br/>
+
+## Composing Agents Together
+
+Agents can call other agents. A "manager" agent can delegate tasks to specialized "worker" agents, each with their own instructions and tools.
+
+```markdown
+---
+model: anthropic:claude-sonnet-4-5
+subagents:
+  researcher:
+    path: ./researcher.pk-agent
+  writer:
+    path: ./writer.pk-agent
+---
+
+Use the researcher to gather information about today's AI news,
+then hand the results to the writer to create a blog post draft.
+```
+
+You can also reference agents with a shorthand - just wrap the name in double brackets:
+
+```markdown
+Use [[researcher]] to find sources, then [[writer]] to draft.
+```
+
+PK-Agent will find the agent files automatically and wire everything up.
+
+<br/>
+
+---
+
+<br/>
+
+## Reusable Skills
+
+If you find yourself writing the same instructions across multiple agents, save them as a **skill** - a reusable block of instructions stored in a `SKILL.md` file.
+
+```
+.pk-agent/
+  skills/
+    summarizer/
+      SKILL.md        <-- reusable instructions
+```
+
+Reference a skill in any agent with triple brackets:
+
+```markdown
+Apply [[[summarizer]]] to the fetched content.
+```
+
+List all available skills:
+
+```
+pk-agent skills
+```
+
+<br/>
+
+---
+
+<br/>
+
+## All Commands
+
+| Command | What it does |
+|---|---|
+| `pk-agent run <file>` | Run an agent |
+| `pk-agent test <target>` | Validate an agent file or URL (no execution) |
+| `pk-agent config <subcommand>` | Manage non-secret defaults (user and project scope) |
+| `pk-agent serve` | Start the HTTP server |
+| `pk-agent auth login` | Connect an AI provider |
+| `pk-agent sessions` | View past agent runs |
+| `pk-agent agents` | List agents in your project |
+| `pk-agent skills` | List available skills |
+| `pk-agent models` | Show supported AI models |
+| `pk-agent add <source>` | Import agents or skills from a URL or repo |
+
+<br/>
+
+---
+
+<br/>
+
+## Platform Support
+
+PK-Agent runs on **Windows**, **macOS**, and **Linux**.
+
+It also works in Docker containers, GitHub Actions, and any CI/CD pipeline - anywhere Node.js runs.
+
+<br/>
+
+---
+
+<br/>
+
+<p align="center">
+  <strong>Apache 2.0 License</strong>
+</p>
+

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js';