@element47/ag 4.5.1 → 4.5.3

package/README.md

@@ -7,14 +7,14 @@ Built as a tool-calling loop with bash — inspired by [How does Claude Code act
 ## Install
 
 ```bash
-npx @iambarryking/ag                  # run directly (prompts for API key on first use)
-npm install -g @iambarryking/ag       # or install globally
+npx @element47/ag                     # run directly (prompts for API key on first use)
+npm install -g @element47/ag          # or install globally
 ```
 
 Or from source:
 
 ```bash
-git clone <repo>
+git clone https://github.com/element47/simple-agent
 cd simple-agent
 npm install && npm run build && npm link
 ```
@@ -127,6 +127,46 @@ export default {
 
 That's it. No config, no registry. Use `/tools` in the REPL to see what's loaded.
 
+### Permission Keys
+
+By default, custom tools require approval for every call (or you allow all calls with `toolname(*)`). To enable fine-grained permission patterns, add a `permissionKey` to your tool:
+
+```js
+// .ag/tools/deploy.mjs
+export default {
+  type: "function",
+  function: {
+    name: "deploy",
+    description: "Deploy to an environment",
+    parameters: {
+      type: "object",
+      properties: {
+        target: { type: "string", enum: ["staging", "production"] },
+        branch: { type: "string" }
+      },
+      required: ["target"]
+    }
+  },
+  permissionKey: { qualifier: "target" },
+  execute: async ({ target, branch }) => { /* ... */ }
+};
+```
+
+Now permission patterns can target specific argument values:
+
+| Pattern | Effect |
+|---------|--------|
+| `deploy(staging)` | Allow staging deploys |
+| `deploy(production)` | Allow production deploys |
+| `deploy(*)` | Allow all deploys |
+
+**`permissionKey` fields:**
+
+- `qualifier` (required) — arg name whose value becomes the pattern qualifier. E.g., `{ qualifier: "target" }` + `target: "staging"` produces `deploy(staging)`.
+- `value` (optional) — arg name whose value is matched by the glob portion. E.g., `{ qualifier: "action", value: "path" }` produces `mytool(read:configs/**)`.
+
+Without `permissionKey`, the only available pattern is `toolname(*)`.
+
 ## Skills
 
 Skills are reusable prompt instructions (with optional tools) that the agent activates on-demand. Browse and install from [skills.sh](https://skills.sh):
@@ -158,6 +198,76 @@ Frontmatter fields: `name` (required), `description` (required), `tools: true` (
 
 The agent sees skill names + descriptions in every prompt. When a task matches, it activates the skill automatically via the `skill` tool, loading the full instructions into context.
 
+## Extensions
+
+Extensions hook into the agent's lifecycle to intercept, modify, or extend behavior. Place TypeScript files in `.ag/extensions/` (project) or `~/.ag/extensions/` (global).
+
+```typescript
+// .ag/extensions/log-tools.ts
+export const name = 'log-tools';
+export const description = 'Logs tool calls and errors';
+
+export default function(agent: any) {
+  agent.on('tool_call', (event: any) => {
+    agent.log(`[log-tools] ${event.toolName}(${JSON.stringify(event.args).slice(0, 80)})`);
+  });
+
+  agent.on('tool_result', (event: any) => {
+    if (event.isError) agent.log(`[log-tools] error in ${event.toolName}: ${event.content.slice(0, 100)}`);
+  });
+}
+```
+
+Extensions export `name` and `description` for the startup display. Use `agent.log()` instead of `process.stderr.write()` for spinner-safe output.
+
+At startup you'll see:
+```
+Loaded: global, 3 skill(s), 1 extension(s)
+  + log-tools  [extension] Logs tool calls and errors
+```
+```
+
+### Available Events
+
+| Event | When | Mutable? |
+|-------|------|----------|
+| `input` | User message arrives | content, skip |
+| `turn_start` | Top of each iteration | Read-only |
+| `before_request` | Before LLM API call | messages, systemPrompt |
+| `after_response` | After LLM response parsed | message |
+| `tool_call` | Before tool executes | args, block, blockReason |
+| `tool_result` | After tool executes | content, isError |
+| `before_compact` | Before context compaction | cancel, customSummary |
+| `turn_end` | After iteration completes | Read-only |
+
+Handlers run sequentially — each handler sees mutations from previous handlers. Use `agent.on(event, handler)` which returns an unsubscribe function. Use `agent.log(message)` for spinner-safe output.
+
+### Examples
+
+Block dangerous commands:
+```typescript
+agent.on('tool_call', (event: any) => {
+  if (event.toolName === 'bash' && event.args.command?.includes('rm -rf /')) {
+    event.block = true;
+    event.blockReason = 'Blocked: dangerous command';
+  }
+});
+```
+
+Inject context before every LLM call:
+```typescript
+agent.on('before_request', (event: any) => {
+  event.systemPrompt += '\n\nAlways respond in Spanish.';
+});
+```
+
+Custom compaction:
+```typescript
+agent.on('before_compact', (event: any) => {
+  event.customSummary = 'Working on auth feature. Files: src/auth.ts, src/middleware.ts';
+});
+```
+
 ## Configuration
 
 Persistent settings are stored in `~/.ag/config.json`:
@@ -234,22 +344,84 @@ Or set it permanently:
 
 ## Permissions
 
-In REPL mode, ag prompts before executing mutating operations:
+In REPL mode, ag prompts before executing mutating operations. You can allow once, remember for the session, or save to the project:
 
 ```
-  ? bash: npm test (y/n) y
+  ? bash: npm test (y)es / (a)lways / (p)roject / (n)o a
+  + Session rule: bash(npm:*)
   ✓ [bash] All tests passed
-  ? file(write): src/utils.ts (y/n) y
+  ? file(write): src/utils.ts (y)es / (a)lways / (p)roject / (n)o p
+  + Saved to .ag/permissions.json: file(write:src/**)
   ✓ [file] Wrote src/utils.ts (24 lines, 680B)
 ```
 
+**Prompt options:**
+- **y** — allow this one time
+- **a** — allow and remember the pattern for this session
+- **p** — allow and save the pattern to project (`.ag/permissions.json`)
+- **n** — deny this one time
+
+### Pattern Syntax
+
+Patterns use `Tool(qualifier:glob)` format:
+
+| Pattern | Matches |
+|---------|---------|
+| `bash(npm:*)` | Any bash command starting with `npm` |
+| `bash(git:*)` | Any bash command starting with `git` |
+| `file(write:src/**)` | File writes anywhere under `src/` |
+| `file(edit:*)` | All file edits |
+| `git(commit)` | Git commit |
+| `web(fetch:*github.com*)` | Fetch from GitHub domains |
+| `bash(*)` | All bash commands |
+| `*` | Everything |
+
+### Rule Scopes
+
+| Scope | Storage | Lifetime |
+|-------|---------|----------|
+| Session | In-memory | Until REPL exits |
+| Project | `.ag/permissions.json` | Persists across sessions |
+| Global | `~/.ag/permissions.json` | Persists everywhere |
+
+Deny rules always override allow rules. Use `/permissions` to manage rules interactively.
+
+### Built-in Classifications
+
 **Always allowed (no prompt):** `file(read)`, `file(list)`, `grep(*)`, `memory(*)`, `plan(*)`, `skill(*)`, `git(status)`, `web(search)`
 
 **Prompted:** `bash`, `file(write)`, `file(edit)`, `git(commit/push/branch)`, `web(fetch)`
 
 **Always blocked:** `rm -rf /`, fork bombs, `sudo rm`, pipe-to-shell (enforced in code regardless of approval)
 
-Skip prompts with `ag -y` or `--yes`. One-shot mode (`ag "query"`) auto-approves.
+Skip all prompts with `ag -y` or `--yes`. One-shot mode (`ag "query"`) auto-approves.
+
+## Guardrails
+
+All externally-loaded tools and skills are scanned at load time for prompt injection and other security issues. This applies to:
+
+- Custom tools (`.mjs` files in `~/.ag/tools/` and `.ag/tools/`)
+- Skills (`SKILL.md` files in `~/.ag/skills/` and `.ag/skills/`)
+- Skills installed from the registry via `/skill add`
+
+**What gets checked:**
+
+| Category | Severity | Examples |
+|----------|----------|---------|
+| Direct injection | Block | "ignore previous instructions", "system override", "reveal prompt" |
+| Encoded payloads | Block | Base64-encoded injection attempts, HTML entity obfuscation |
+| Hidden content | Block | HTML comments with instructions, zero-width characters, control chars |
+| Exfiltration | Block/Warn | `fetch()` calls in descriptions (block), URLs/emails (warn) |
+| Suspicious overrides | Warn | "bypass security", "auto-approve", "run without permission" |
+
+**Blocked** items are skipped entirely with a warning. **Warned** items still load but emit a warning to stderr:
+
+```
+Warning: evil-tool.mjs blocked by guardrails: tool "evil" description: prompt injection: "ignore previous instructions"
+Warning: shady-tool.mjs: tool "shady" description: description contains URL
+```
+
+When installing a skill from the registry, files are scanned before being written to disk. If the core `SKILL.md` is blocked, the entire installation is aborted.
 
 ## Streaming
 
@@ -275,7 +447,7 @@ Tools execute in parallel when the model returns multiple tool calls.
 - For multi-step coding tasks, the agent creates a plan before starting and updates it as it goes.
 - For simple questions, it just answers directly.
 - At 25 iterations the REPL asks if you want to continue.
-- At 90% context window usage, ag automatically summarizes older conversation messages to free space. Use `/compact` to trigger manually. Only message history is compacted — system prompt, tools, and skills are unaffected.
+- At 90% context window usage, ag automatically summarizes older conversation messages to free space. Use `/context compact` to trigger manually. Only message history is compacted — system prompt, tools, and skills are unaffected.
 
 ## When to use something else
 
@@ -300,6 +472,10 @@ src/
   core/types.ts       # interfaces
   core/colors.ts      # ANSI colors (respects NO_COLOR)
   core/version.ts     # version from package.json
+  core/constants.ts   # AG_DIR, ignore patterns, binary detection
+  core/guardrails.ts  # prompt injection scanning (5 threat categories)
+  core/loader.ts      # custom tool loader (~/.ag/tools/, .ag/tools/)
+  core/permissions.ts # permission manager with glob pattern matching
   memory/memory.ts    # three-tier file memory
   tools/file.ts       # file reading + directory listing
   tools/bash.ts       # shell execution (with command safeguards)

package/dist/cli/__tests__/repl-rawmode.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=repl-rawmode.test.d.ts.map

package/dist/cli/__tests__/repl-rawmode.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repl-rawmode.test.d.ts","sourceRoot":"","sources":["../../../src/cli/__tests__/repl-rawmode.test.ts"],"names":[],"mappings":""}

package/dist/cli/__tests__/repl-rawmode.test.js

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+/**
+ * Structural tests for the REPL's raw-mode / interrupt handling.
+ *
+ * The REPL relies on readline managing raw mode (set at construction,
+ * cleared at close). The interrupt-detection code (escape key listener)
+ * must NOT toggle setRawMode itself — doing so leaves stdin in cooked
+ * mode after the agent run, causing readline to double-echo user input.
+ *
+ * These tests read the source to enforce that invariant so the bug
+ * cannot silently regress.
+ */
+const replSource = readFileSync(resolve(import.meta.dirname, '..', 'repl.ts'), 'utf-8');
+describe('REPL interrupt handling — raw mode invariant', () => {
+    // Extract the runAgent closure body (between `const runAgent` and the next
+    // top-level `await runAgent`).  We look for setRawMode calls inside it.
+    const runAgentMatch = replSource.match(/const runAgent = async[\s\S]*?finally\s*\{[\s\S]*?\}\s*\}/);
+    const runAgentBody = runAgentMatch?.[0] ?? '';
+    it('runAgent body is found in source', () => {
+        expect(runAgentBody.length).toBeGreaterThan(100);
+    });
+    it('does NOT call setRawMode(true) inside runAgent', () => {
+        // readline manages raw mode; the interrupt setup must not override it
+        expect(runAgentBody).not.toMatch(/setRawMode\s*\(\s*true\s*\)/);
+    });
+    it('does NOT call setRawMode(false) inside runAgent', () => {
+        // Turning raw mode off after agent run breaks readline's next question()
+        expect(runAgentBody).not.toMatch(/setRawMode\s*\(\s*false\s*\)/);
+    });
+    it('pauses readline before adding keypress listener', () => {
+        // Must pause rl to detach its keypress handler before we add ours
+        const pauseIdx = runAgentBody.indexOf('.rl.pause()');
+        const onKeypressIdx = runAgentBody.indexOf("on('keypress'");
+        expect(pauseIdx).toBeGreaterThan(-1);
+        expect(onKeypressIdx).toBeGreaterThan(-1);
+        expect(pauseIdx).toBeLessThan(onKeypressIdx);
+    });
+    it('removes keypress listener in finally block', () => {
+        const finallyMatch = runAgentBody.match(/finally\s*\{[\s\S]*\}/);
+        expect(finallyMatch).not.toBeNull();
+        expect(finallyMatch[0]).toMatch(/removeListener\s*\(\s*['"]keypress['"]/);
+    });
+});
+//# sourceMappingURL=repl-rawmode.test.js.map

package/dist/cli/__tests__/repl-rawmode.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repl-rawmode.test.js","sourceRoot":"","sources":["../../../src/cli/__tests__/repl-rawmode.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;;;;;;;;GAUG;AAEH,MAAM,UAAU,GAAG,YAAY,CAC7B,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,EAC7C,OAAO,CACR,CAAC;AAEF,QAAQ,CAAC,8CAA8C,EAAE,GAAG,EAAE;IAC5D,2EAA2E;IAC3E,wEAAwE;IACxE,MAAM,aAAa,GAAG,UAAU,CAAC,KAAK,CACpC,2DAA2D,CAC5D,CAAC;IACF,MAAM,YAAY,GAAG,aAAa,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAE9C,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC1C,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,sEAAsE;QACtE,MAAM,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,6BAA6B,CAAC,CAAC;IAClE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,yEAAyE;QACzE,MAAM,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,8BAA8B,CAAC,CAAC;IACnE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,kEAAkE;QAClE,MAAM,QAAQ,GAAG,YAAY,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QACrD,MAAM,aAAa,GAAG,YAAY,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;QAC5D,MAAM,CAAC,QAAQ,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;QACrC,MAAM,CAAC,aAAa,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1C,MAAM,CAAC,QAAQ,CAAC,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACpD,MAAM,YAAY,GAAG,YAAY,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;QACjE,MAAM,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QACpC,MAAM,CAAC,YAAa,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,wCAAwC,CAAC,CAAC;IAC7E,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/cli/repl.d.ts

@@ -1,14 +1,19 @@
 import { Interface } from 'node:readline';
 import { Agent } from '../core/agent.js';
+import { PermissionManager } from '../core/permissions.js';
 import type { ConfirmToolCall } from '../core/types.js';
 export declare function createConfirmCallback(sharedRl?: Interface): ConfirmToolCall & {
     pauseSpinner: (() => void) | null;
 };
+export declare function createPermissionCallback(pm: PermissionManager, sharedRl?: Interface): ConfirmToolCall & {
+    pauseSpinner: (() => void) | null;
+};
 export declare class REPL {
     private readonly agent;
     private readonly rl;
-    private readonly confirmCb;
-    constructor(agent: Agent, confirmCb?: ReturnType<typeof createConfirmCallback>);
+    private readonly pm;
+    private confirmCb;
+    constructor(agent: Agent, pm?: PermissionManager, confirmCb?: ReturnType<typeof createPermissionCallback>);
     start(): Promise<void>;
     private handleCommand;
     private ask;

package/dist/cli/repl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repl.d.ts","sourceRoot":"","sources":["../../src/cli/repl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,SAAS,EAAsB,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,KAAK,EAA0B,MAAM,kBAAkB,CAAC;AAKjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAoBxD,wBAAgB,qBAAqB,CAAC,QAAQ,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG;IAAE,YAAY,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAA;CAAE,CAuBnH;AA8GD,qBAAa,IAAI;IACf,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAY;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkD;gBAEhE,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,UAAU,CAAC,OAAO,qBAAqB,CAAC;IAcxE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YA6Ld,aAAa;IAwU3B,OAAO,CAAC,GAAG;CAGZ"}
+{"version":3,"file":"repl.d.ts","sourceRoot":"","sources":["../../src/cli/repl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,SAAS,EAAsB,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAKzC,OAAO,EAAE,iBAAiB,EAAgB,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,kBAAkB,CAAC;AAqCvE,wBAAgB,qBAAqB,CAAC,QAAQ,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG;IAAE,YAAY,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAA;CAAE,CAgBnH;AAED,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,iBAAiB,EAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG;IAAE,YAAY,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAA;CAAE,CAiD7I;AA8GD,qBAAa,IAAI;IACf,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAY;IAC/B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAA2B;IAC9C,OAAO,CAAC,SAAS,CAAqD;gBAE1D,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,iBAAiB,EAAE,SAAS,CAAC,EAAE,UAAU,CAAC,OAAO,wBAAwB,CAAC;IAqBnG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAwNd,aAAa;IA+Y3B,OAAO,CAAC,GAAG;CAGZ"}