@sleepy-ai/cli 0.0.0-main-202607032053 → 0.1.4

package/src/skill/builtin/.bundle/self-extend/reference/hook-api.md

@@ -0,0 +1,242 @@
+# Hook API Reference
+
+## File Format
+
+```ts
+import type { Hooks } from "@sleepy-ai/plugin"
+
+const hooks: Hooks = {
+  "event.name": async (input, output) => {
+    // Mutate `output` to modify behavior
+  },
+}
+
+export default hooks
+```
+
+Each file exports a single Hooks object. Multiple events can be handled in one file.
+
+## Event Reference
+
+### tool.execute.before
+
+Fires before any tool executes. Can modify args or cancel.
+
+```ts
+"tool.execute.before": async (input, output) => {
+  // input (read-only):
+  //   input.tool: string      — tool id ("bash", "write", "edit", etc.)
+  //   input.sessionID: string
+  //   input.callID: string
+
+  // output (mutable):
+  //   output.args: any        — tool arguments, mutate to change
+  //   output.cancel?: boolean — set true to block execution
+  //   output.cancelReason?: string — shown to LLM as tool result
+}
+```
+
+### tool.execute.after
+
+Fires after tool execution. Can modify the result.
+
+```ts
+"tool.execute.after": async (input, output) => {
+  // input (read-only):
+  //   input.tool: string
+  //   input.sessionID: string
+  //   input.callID: string
+  //   input.args: any         — the args that were used
+
+  // output (mutable):
+  //   output.title: string
+  //   output.output: string   — the tool's text output
+  //   output.metadata: any
+}
+```
+
+### tool.definition
+
+Modify tool descriptions/parameters sent to LLM.
+
+```ts
+"tool.definition": async (input, output) => {
+  // input.toolID: string
+
+  // output (mutable):
+  //   output.description: string  — tool description
+  //   output.parameters: any      — JSON Schema for parameters
+}
+```
+
+### chat.params
+
+Modify LLM request parameters.
+
+```ts
+"chat.params": async (input, output) => {
+  // input (read-only):
+  //   input.sessionID: string
+  //   input.agent: string
+  //   input.model: Model
+  //   input.provider: ProviderContext
+
+  // output (mutable):
+  //   output.temperature: number
+  //   output.topP: number
+  //   output.topK: number
+  //   output.maxOutputTokens: number | undefined
+  //   output.options: Record<string, any>
+}
+```
+
+### chat.headers
+
+Add custom HTTP headers to LLM requests.
+
+```ts
+"chat.headers": async (input, output) => {
+  // input: same as chat.params
+  // output.headers: Record<string, string>  — mutate to add headers
+}
+```
+
+### experimental.chat.system.transform
+
+Modify the system prompt sent to LLM.
+
+```ts
+"experimental.chat.system.transform": async (input, output) => {
+  // input.sessionID?: string
+  // input.model: Model
+
+  // output.system: string[]  — array of system prompt sections
+  // Push to append, splice to insert, replace to override
+  output.system.push("Always respond concisely.")
+}
+```
+
+### experimental.chat.messages.transform
+
+Modify the message list sent to LLM.
+
+```ts
+"experimental.chat.messages.transform": async (input, output) => {
+  // output.messages: Array<{ info: Message, parts: Part[] }>
+  // Filter, reorder, or modify messages before they reach the model
+}
+```
+
+### permission.ask
+
+Auto-allow or deny permission requests.
+
+> **Note:** Defined in the Hooks interface but not yet wired in the permission system. Writing this hook is safe (no-op until upstream integrates it).
+
+```ts
+"permission.ask": async (input, output) => {
+  // input: Permission object (permission name, patterns, metadata)
+  // output.status: "ask" | "deny" | "allow"
+  
+  // Example: auto-allow all read operations
+  if (input.permission === "read") {
+    output.status = "allow"
+  }
+}
+```
+
+### shell.env
+
+Inject environment variables into shell execution.
+
+```ts
+"shell.env": async (input, output) => {
+  // input.cwd: string
+  // input.sessionID?: string
+  // output.env: Record<string, string>
+  
+  output.env.NODE_ENV = "development"
+  output.env.DEBUG = "true"
+}
+```
+
+### command.execute.before
+
+Inject content before a slash command runs.
+
+```ts
+"command.execute.before": async (input, output) => {
+  // input.command: string
+  // input.sessionID: string
+  // input.arguments: string
+  // output.parts: Part[]  — prepend parts to the command
+}
+```
+
+### experimental.session.compacting
+
+Customize the compaction prompt.
+
+```ts
+"experimental.session.compacting": async (input, output) => {
+  // input.sessionID: string
+  // output.context: string[]  — additional context for compaction prompt
+  // output.prompt?: string    — if set, replaces default compaction prompt entirely
+}
+```
+
+### chat.message
+
+Called when a new message is received.
+
+```ts
+"chat.message": async (input, output) => {
+  // input.sessionID: string
+  // input.agent?: string
+  // input.model?: { providerID, modelID }
+  // output.message: UserMessage
+  // output.parts: Part[]
+}
+```
+
+## Examples
+
+### Safety guard
+```ts
+export default {
+  "tool.execute.before": async (input, output) => {
+    if (input.tool === "bash") {
+      const cmd = output.args.command ?? ""
+      if (/rm\s+-rf\s+\//.test(cmd)) {
+        output.cancel = true
+        output.cancelReason = "Blocked: dangerous rm -rf on root"
+      }
+    }
+  },
+}
+```
+
+### Auto-approve reads
+```ts
+export default {
+  "permission.ask": async (input, output) => {
+    if (input.permission === "read" || input.permission === "glob" || input.permission === "grep") {
+      output.status = "allow"
+    }
+  },
+}
+```
+
+### Inject project context into system prompt
+```ts
+import { readFileSync } from "fs"
+
+export default {
+  "experimental.chat.system.transform": async (input, output) => {
+    try {
+      const ctx = readFileSync(".mimocode/project-context.md", "utf-8")
+      output.system.push(ctx)
+    } catch {}
+  },
+}
+```

package/src/skill/builtin/.bundle/self-extend/reference/skill-api.md

@@ -0,0 +1,114 @@
+# Skill API Reference
+
+## File Structure
+
+```
+.mimocode/skills/<skill-name>/
+├── SKILL.md              # Required — main skill document
+├── supporting-file.md    # Optional — reference material
+└── scripts/              # Optional — executable scripts
+    └── helper.sh
+```
+
+## SKILL.md Format
+
+```markdown
+---
+name: my-skill-name
+description: Use when [triggering conditions]
+---
+
+# Skill Title
+
+Content loaded into conversation when the skill is invoked.
+```
+
+### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | yes | Unique identifier (letters, numbers, hyphens only) |
+| `description` | yes | When to use — starts with "Use when..." (max ~500 chars) |
+| `hidden` | no | If `true`, not shown in skill list (agent can still load by name) |
+
+### Description Guidelines
+
+- Start with "Use when..." — focus on **triggering conditions**, not what the skill does
+- Don't summarize the workflow (agent may follow the summary instead of reading the full content)
+- Include symptoms, situations, contexts that signal this skill applies
+- Write in third person
+
+```yaml
+# ❌ BAD: summarizes workflow
+description: Creates tools and hooks by writing files to .mimocode directories
+
+# ✅ GOOD: triggering conditions only
+description: Use when you want to evolve your own capabilities or notice repeated patterns worth automating
+```
+
+## Skill Content
+
+The body after frontmatter is injected into the conversation when the skill is loaded. It can contain:
+
+- Instructions and workflows
+- Code examples (inline)
+- Reference to supporting files via `@filename.md` (loads the file)
+- Flowcharts (DOT format)
+- Tables, lists, any markdown
+
+## Referencing Supporting Files
+
+Use `@filename` to reference files in the same skill directory:
+
+```markdown
+See @reference/detailed-api.md for the full API specification.
+```
+
+The file content is loaded on demand when the agent accesses it.
+
+## Examples
+
+### Simple technique skill
+```markdown
+---
+name: retry-pattern
+description: Use when implementing retry logic, handling transient failures, or dealing with flaky external services
+---
+
+# Retry Pattern
+
+## Core Pattern
+\```ts
+async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
+  for (let i = 0; i < maxRetries; i++) {
+    try { return await fn() }
+    catch (e) { if (i === maxRetries - 1) throw e; await sleep(2 ** i * 100) }
+  }
+  throw new Error("unreachable")
+}
+\```
+
+## When NOT to use
+- Deterministic errors (400, 404) — retrying won't help
+- Operations with side effects that can't be repeated safely
+```
+
+### Reference skill with supporting files
+```markdown
+---
+name: project-api
+description: Use when working with this project's REST API endpoints, authentication, or data models
+---
+
+# Project API Reference
+
+See @endpoints.md for the full endpoint list.
+See @auth.md for authentication flow.
+See @models.md for data model schemas.
+```
+
+## Hot-Reload Behavior
+
+- New skills appear in the available skills list on the next turn
+- Modified skills are reloaded on the next turn
+- The agent can invoke skills via the skill tool or `/skill-name`

package/src/skill/builtin/.bundle/self-extend/reference/tool-api.md

@@ -0,0 +1,115 @@
+# Tool API Reference
+
+## File Format
+
+```ts
+import { tool } from "@sleepy-ai/plugin"
+
+// Single tool (default export)
+export default tool({
+  description: string,       // LLM reads this to decide when to use
+  args: {                    // Zod schema for parameters
+    [key]: tool.schema.xxx()
+  },
+  execute: async (args, ctx) => string | { output: string, metadata?: Record<string, any> }
+})
+
+// Multiple tools (named exports)
+export const myTool = tool({ ... })
+export const otherTool = tool({ ... })
+```
+
+## tool.schema (Zod)
+
+```ts
+tool.schema.string()                    // z.string()
+tool.schema.string().optional()         // z.string().optional()
+tool.schema.string().describe("...")    // with description for LLM
+tool.schema.number()                    // z.number()
+tool.schema.boolean()                   // z.boolean()
+tool.schema.enum(["a", "b", "c"])       // z.enum([...])
+tool.schema.array(tool.schema.string()) // z.array(z.string())
+tool.schema.object({ key: tool.schema.string() })
+```
+
+## ToolContext (ctx)
+
+```ts
+type ToolContext = {
+  sessionID: string        // Current session
+  messageID: string        // Current message
+  agent: string            // Agent name ("general", "explore", etc.)
+  directory: string        // Project root (use for file paths)
+  worktree: string         // Git worktree root
+  abort: AbortSignal       // Cancelled when user interrupts
+  metadata(input: {        // Update tool call display
+    title?: string
+    metadata?: Record<string, any>
+  }): void
+}
+```
+
+## Return Value
+
+```ts
+// Simple string output
+return "Result text shown to LLM"
+
+// Structured output with metadata
+return {
+  output: "Result text",
+  metadata: {
+    // Arbitrary data, shown in TUI tool result panel
+    files_changed: 3,
+    duration_ms: 1200,
+  }
+}
+```
+
+## Examples
+
+### Wrap a shell command
+```ts
+import { tool } from "@sleepy-ai/plugin"
+import { execSync } from "child_process"
+
+export default tool({
+  description: "Check if a port is in use",
+  args: {
+    port: tool.schema.number().describe("Port number to check"),
+  },
+  async execute(args, ctx) {
+    try {
+      const result = execSync(`lsof -i :${args.port}`, { encoding: "utf-8", cwd: ctx.directory })
+      return `Port ${args.port} is in use:\n${result}`
+    } catch {
+      return `Port ${args.port} is free`
+    }
+  },
+})
+```
+
+### HTTP API call
+```ts
+import { tool } from "@sleepy-ai/plugin"
+
+export default tool({
+  description: "Query project's health endpoint",
+  args: {
+    endpoint: tool.schema.string().optional().describe("Path (default: /health)"),
+  },
+  async execute(args, ctx) {
+    const url = `http://localhost:3000${args.endpoint ?? "/health"}`
+    const res = await fetch(url, { signal: ctx.abort })
+    const body = await res.text()
+    return `${res.status} ${res.statusText}\n${body}`
+  },
+})
+```
+
+## Constraints
+
+- Output truncated at 50KB / 2000 lines
+- Use `ctx.abort` for cancellable long-running operations
+- Tool id is derived from filename (e.g., `deploy-check.ts` → tool id `deploy-check`)
+- Same id as a builtin overrides it (bash, read, edit, write, glob, grep, etc.)