portable-agent-layer 0.67.0 → 0.69.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. package/README.md +1 -0
  2. package/assets/skills/pal-analyze/SKILL.md +1 -1
  3. package/assets/skills/pal-reflect/SKILL.md +1 -1
  4. package/assets/skills/projects/SKILL.md +1 -1
  5. package/assets/skills/telos/SKILL.md +1 -1
  6. package/assets/templates/hooks.codex.json +18 -4
  7. package/assets/templates/hooks.copilot.json +31 -12
  8. package/assets/templates/hooks.cursor.json +23 -7
  9. package/assets/templates/settings.claude.json +12 -12
  10. package/package.json +1 -1
  11. package/src/cli/index.ts +16 -3
  12. package/src/cli/ledger.ts +329 -0
  13. package/src/hooks/LedgerCommit.ts +7 -21
  14. package/src/hooks/LedgerSnapshot.ts +7 -14
  15. package/src/hooks/LedgerUnapplied.ts +17 -15
  16. package/src/hooks/LoadContext.ts +4 -2
  17. package/src/hooks/lib/actor.ts +4 -4
  18. package/src/hooks/lib/agent.ts +91 -11
  19. package/src/hooks/lib/ledger-hook.ts +186 -17
  20. package/src/hooks/lib/ledger.ts +25 -5
  21. package/src/hooks/lib/sensitive-path.ts +117 -0
  22. package/src/hooks/lib/settings.ts +5 -0
  23. package/src/targets/lib.ts +17 -3
  24. package/src/targets/opencode/plugin.ts +22 -0
  25. package/src/tools/agent/project.ts +28 -3
  26. package/src/tools/ledger/query.ts +300 -0
package/README.md CHANGED
@@ -88,6 +88,7 @@ pal cli status # check your setup
88
88
  | `pal cli actor [label <name>]` | Show or rename the actor — who caused a record. Travels with an export, so a shared memory can tell two people apart |
89
89
  | `pal cli machine [label <name>]` | Show or rename this install — where a record was written. Never leaves the machine |
90
90
  | `pal cli knowledge` | Query & manage the knowledge store (search, graph, stats, hubs, find, show, add, ls, ingest) |
91
+ | `pal cli ledger` | Query the action ledger — `log`, `show <id>`, `stats`, filtered by `--project`, `--since`, `--actor`, `--machine`, `--runtime`, `--outcome`, `--tool`, `--target` |
91
92
  | `pal cli skill link <name>` | Link a personal `~/.pal/skills/<name>/` into every installed agent so it is discoverable |
92
93
  | `pal cli skill doctor <name>` | Evaluate a skill against the authoring best practices (folder/file-name match, name, description, body length, point-of-view, reference depth) |
93
94
  | `pal cli subagent link <name>` | Install a personal `~/.pal/agents/<name>.md` (merged multi-platform definition) into every installed agent, split per platform |
package/assets/skills/pal-analyze/SKILL.md CHANGED
@@ -2,7 +2,7 @@
2
2
  name: pal-analyze
3
3
  license: MIT
4
4
  description: "Run learning analysis — surface rating trends, recurring failure patterns, and graduation candidates. Use when learning analysis is due, or when the user asks about performance patterns, low ratings, or what to improve."
5
- argument-hint: [optional: --actionable for AI-generated recommendations]
5
+ argument-hint: "[optional: --actionable for AI-generated recommendations]"
6
6
  metadata:
7
7
  source: portable-agent-layer
8
8
  triggers:
package/assets/skills/pal-reflect/SKILL.md CHANGED
@@ -2,7 +2,7 @@
2
2
  name: pal-reflect
3
3
  license: MIT
4
4
  description: "Run relationship reflect — promote recurring behavioral observations into tracked opinions. Use when relationship reflect is due, or when the user asks to review what patterns have been observed."
5
- argument-hint: [optional: --dry-run to preview without writing]
5
+ argument-hint: "[optional: --dry-run to preview without writing]"
6
6
  metadata:
7
7
  source: portable-agent-layer
8
8
  triggers:
package/assets/skills/projects/SKILL.md CHANGED
@@ -2,7 +2,7 @@
2
2
  name: projects
3
3
  license: MIT
4
4
  description: "Project context management. PROACTIVE — use when the user references a project (by name or as \"this repo\", \"current work\"), asks to add/update/complete a project, says \"store under a named project\", \"track this\", \"what am I working on\", \"my projects\", \"my priorities\". Also triggered by ISC/ISA terminology — ISC stands for Ideal State Criteria, a project's verifiable done-conditions stored as `ISC-N:` lines in the Criteria section of its ISA.md spec. Phrases like \"ISC\", \"open/opening the ISC\", \"open ISCs\" (unfinished criteria), \"create/creating a ticket for a project\", \"new ticket\", or \"project ticket\" all map here: use `list-isc` to read them, `add-isc` to create one, `complete-isc`/`reopen-isc` to change status."
5
- argument-hint: [list | create | resume | add-next | add-blocker | add-decision | add-handoff | update-section | criteria | isa-init | complete | archive | pause]
5
+ argument-hint: "[list | create | resume | add-next | add-blocker | add-decision | add-handoff | update-section | criteria | isa-init | complete | archive | pause]"
6
6
  metadata:
7
7
  source: portable-agent-layer
8
8
  triggers:
package/assets/skills/telos/SKILL.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: telos
3
3
  description: "Personal context management. Use when discussing goals, beliefs, challenges, identity, updating telos, life context, changing a goal, what do I believe, current obstacles, mission, or strategies."
4
- argument-hint: [area to view or update]
4
+ argument-hint: "[area to view or update]"
5
5
  metadata:
6
6
  source: portable-agent-layer
7
7
  derived-from: https://github.com/danielmiessler/LifeOS
package/assets/templates/hooks.codex.json CHANGED
@@ -5,7 +5,7 @@
5
5
  "hooks": [
6
6
  {
7
7
  "type": "command",
8
- "command": "PAL_AGENT=codex bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts"
8
+ "command": "bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts --agent=codex"
9
9
  }
10
10
  ]
11
11
  }
@@ -15,7 +15,7 @@
15
15
  "hooks": [
16
16
  {
17
17
  "type": "command",
18
- "command": "PAL_AGENT=codex bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts"
18
+ "command": "bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts --agent=codex"
19
19
  }
20
20
  ]
21
21
  }
@@ -25,7 +25,21 @@
25
25
  "hooks": [
26
26
  {
27
27
  "type": "command",
28
- "command": "PAL_AGENT=codex bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts"
28
+ "command": "bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts --agent=codex"
29
+ },
30
+ {
31
+ "type": "command",
32
+ "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerSnapshot.ts --agent=codex"
33
+ }
34
+ ]
35
+ }
36
+ ],
37
+ "PostToolUse": [
38
+ {
39
+ "hooks": [
40
+ {
41
+ "type": "command",
42
+ "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts --agent=codex"
29
43
  }
30
44
  ]
31
45
  }
@@ -35,7 +49,7 @@
35
49
  "hooks": [
36
50
  {
37
51
  "type": "command",
38
- "command": "PAL_AGENT=codex bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts"
52
+ "command": "bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts --agent=codex"
39
53
  }
40
54
  ]
41
55
  }
package/assets/templates/hooks.copilot.json CHANGED
@@ -4,39 +4,58 @@
4
4
  "sessionStart": [
5
5
  {
6
6
  "type": "command",
7
- "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts",
8
- "powershell": "$env:PAL_AGENT='copilot'; bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts"
7
+ "bash": "bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts --agent=copilot",
8
+ "powershell": "bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts --agent=copilot"
9
9
  }
10
10
  ],
11
11
  "userPromptSubmitted": [
12
12
  {
13
13
  "type": "command",
14
- "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts",
15
- "powershell": "$env:PAL_AGENT='copilot'; bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts"
14
+ "bash": "bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts --agent=copilot",
15
+ "powershell": "bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts --agent=copilot"
16
16
  }
17
17
  ],
18
18
  "preToolUse": [
19
19
  {
20
20
  "type": "command",
21
- "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts",
22
- "powershell": "$env:PAL_AGENT='copilot'; bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts"
21
+ "bash": "bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts --agent=copilot",
22
+ "powershell": "bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts --agent=copilot"
23
23
  },
24
24
  {
25
25
  "type": "command",
26
- "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts",
27
- "powershell": "$env:PAL_AGENT='copilot'; bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
26
+ "bash": "bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts --agent=copilot",
27
+ "powershell": "bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts --agent=copilot"
28
28
  },
29
29
  {
30
30
  "type": "command",
31
- "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts",
32
- "powershell": "$env:PAL_AGENT='copilot'; bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts"
31
+ "bash": "bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts --agent=copilot",
32
+ "powershell": "bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts --agent=copilot"
33
+ },
34
+ {
35
+ "type": "command",
36
+ "bash": "bun run {{PKG_ROOT}}/src/hooks/LedgerSnapshot.ts --agent=copilot",
37
+ "powershell": "bun run {{PKG_ROOT}}/src/hooks/LedgerSnapshot.ts --agent=copilot"
38
+ }
39
+ ],
40
+ "postToolUse": [
41
+ {
42
+ "type": "command",
43
+ "bash": "bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts --agent=copilot",
44
+ "powershell": "bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts --agent=copilot"
45
+ }
46
+ ],
47
+ "postToolUseFailure": [
48
+ {
49
+ "type": "command",
50
+ "bash": "bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts --agent=copilot --event=postToolUseFailure",
51
+ "powershell": "bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts --agent=copilot --event=postToolUseFailure"
33
52
  }
34
53
  ],
35
54
  "agentStop": [
36
55
  {
37
56
  "type": "command",
38
- "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts",
39
- "powershell": "$env:PAL_AGENT='copilot'; bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts"
57
+ "bash": "bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts --agent=copilot",
58
+ "powershell": "bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts --agent=copilot"
40
59
  }
41
60
  ]
42
61
  }
package/assets/templates/hooks.cursor.json CHANGED
@@ -4,39 +4,55 @@
4
4
  "sessionStart": [
5
5
  {
6
6
  "type": "command",
7
- "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts"
7
+ "command": "bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts --agent=cursor"
8
8
  }
9
9
  ],
10
10
  "beforeSubmitPrompt": [
11
11
  {
12
12
  "type": "command",
13
- "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts"
13
+ "command": "bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts --agent=cursor"
14
14
  }
15
15
  ],
16
16
  "preToolUse": [
17
17
  {
18
18
  "type": "command",
19
- "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts"
19
+ "command": "bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts --agent=cursor"
20
20
  },
21
21
  {
22
22
  "type": "command",
23
- "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
23
+ "command": "bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts --agent=cursor"
24
24
  },
25
25
  {
26
26
  "type": "command",
27
- "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts"
27
+ "command": "bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts --agent=cursor"
28
+ },
29
+ {
30
+ "type": "command",
31
+ "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerSnapshot.ts --agent=cursor"
32
+ }
33
+ ],
34
+ "postToolUse": [
35
+ {
36
+ "type": "command",
37
+ "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts --agent=cursor"
38
+ }
39
+ ],
40
+ "postToolUseFailure": [
41
+ {
42
+ "type": "command",
43
+ "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts --agent=cursor"
28
44
  }
29
45
  ],
30
46
  "beforeShellExecution": [
31
47
  {
32
48
  "type": "command",
33
- "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts"
49
+ "command": "bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts --agent=cursor"
34
50
  }
35
51
  ],
36
52
  "stop": [
37
53
  {
38
54
  "type": "command",
39
- "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts"
55
+ "command": "bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts --agent=cursor"
40
56
  }
41
57
  ]
42
58
  }
package/assets/templates/settings.claude.json CHANGED
@@ -69,7 +69,7 @@
69
69
  "hooks": [
70
70
  {
71
71
  "type": "command",
72
- "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts"
72
+ "command": "bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts --agent=claude"
73
73
  }
74
74
  ]
75
75
  },
@@ -78,7 +78,7 @@
78
78
  "hooks": [
79
79
  {
80
80
  "type": "command",
81
- "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/CompactRecover.ts"
81
+ "command": "bun run {{PKG_ROOT}}/src/hooks/CompactRecover.ts --agent=claude"
82
82
  }
83
83
  ]
84
84
  }
@@ -89,7 +89,7 @@
89
89
  "hooks": [
90
90
  {
91
91
  "type": "command",
92
- "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/PreCompactPersist.ts"
92
+ "command": "bun run {{PKG_ROOT}}/src/hooks/PreCompactPersist.ts --agent=claude"
93
93
  }
94
94
  ]
95
95
  }
@@ -100,7 +100,7 @@
100
100
  "hooks": [
101
101
  {
102
102
  "type": "command",
103
- "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts"
103
+ "command": "bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts --agent=claude"
104
104
  }
105
105
  ]
106
106
  }
@@ -111,7 +111,7 @@
111
111
  "hooks": [
112
112
  {
113
113
  "type": "command",
114
- "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts"
114
+ "command": "bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts --agent=claude"
115
115
  }
116
116
  ]
117
117
  },
@@ -120,7 +120,7 @@
120
120
  "hooks": [
121
121
  {
122
122
  "type": "command",
123
- "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
123
+ "command": "bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts --agent=claude"
124
124
  }
125
125
  ]
126
126
  },
@@ -129,7 +129,7 @@
129
129
  "hooks": [
130
130
  {
131
131
  "type": "command",
132
- "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts"
132
+ "command": "bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts --agent=claude"
133
133
  }
134
134
  ]
135
135
  },
@@ -138,7 +138,7 @@
138
138
  "hooks": [
139
139
  {
140
140
  "type": "command",
141
- "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/LedgerSnapshot.ts"
141
+ "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerSnapshot.ts --agent=claude"
142
142
  }
143
143
  ]
144
144
  }
@@ -149,7 +149,7 @@
149
149
  "hooks": [
150
150
  {
151
151
  "type": "command",
152
- "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts"
152
+ "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts --agent=claude"
153
153
  }
154
154
  ]
155
155
  }
@@ -160,7 +160,7 @@
160
160
  "hooks": [
161
161
  {
162
162
  "type": "command",
163
- "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts"
163
+ "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts --agent=claude"
164
164
  }
165
165
  ]
166
166
  }
@@ -171,7 +171,7 @@
171
171
  "hooks": [
172
172
  {
173
173
  "type": "command",
174
- "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts"
174
+ "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts --agent=claude"
175
175
  }
176
176
  ]
177
177
  }
@@ -182,7 +182,7 @@
182
182
  "hooks": [
183
183
  {
184
184
  "type": "command",
185
- "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts"
185
+ "command": "bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts --agent=claude"
186
186
  }
187
187
  ]
188
188
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "portable-agent-layer",
3
- "version": "0.67.0",
3
+ "version": "0.69.0",
4
4
  "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
5
5
  "type": "module",
6
6
  "bin": {
package/src/cli/index.ts CHANGED
@@ -16,6 +16,7 @@
16
16
  * status Show current PAL configuration
17
17
  * doctor Check prerequisites and system health
18
18
  * usage Summarize token usage and cost
19
+ * ledger <sub> [filters] Query the action ledger (log · show · stats)
19
20
  * skill link <name> Link a personal ~/.pal/skills/<name>/ into installed agents
20
21
  * skill doctor <name|--all> Evaluate one skill, or every installed skill, against the authoring best practices
21
22
  * subagent link <name> Install a personal ~/.pal/agents/<name>.md into installed agents
@@ -232,6 +233,12 @@ async function runCli(command: string | undefined, args: string[]) {
232
233
  if (code !== 0) process.exit(code);
233
234
  break;
234
235
  }
236
+ case "ledger": {
237
+ const { runLedger } = await import("./ledger");
238
+ const code = await runLedger(args);
239
+ if (code !== 0) process.exit(code);
240
+ break;
241
+ }
235
242
  case "subagent": {
236
243
  const { runSubagent } = await import("./subagent");
237
244
  const code = await runSubagent(args);
@@ -299,6 +306,8 @@ function showHelp() {
299
306
  pal cli machine [label <name>] Show or rename this install (where it was written)
300
307
  pal cli knowledge <sub> [args] Query & manage the knowledge store
301
308
  (search · graph · stats · hubs · find · show · add · ls)
309
+ pal cli ledger <sub> [filters] Query the action ledger (log · show · stats)
310
+ e.g. ledger log --project X --since 7d
302
311
  pal cli skill link <name> Link a personal ~/.pal/skills/<name>/ into installed agents
303
312
  pal cli skill doctor <name|--all> Evaluate one skill, or every installed skill
304
313
  pal cli skill author-model Print the flagship model that authors skills for the active agent
@@ -469,7 +478,11 @@ function checkCodexHooksRegistered(): boolean {
469
478
  }
470
479
 
471
480
  function checkCopilotInstructionsPresent(): boolean {
472
- return existsSync(resolve(platform.copilotDir(), "copilot-instructions.md"));
481
+ const instructionsDir = resolve(platform.copilotDir(), "instructions");
482
+ if (!existsSync(instructionsDir)) return false;
483
+ return readdirSync(instructionsDir).some(
484
+ (f) => f.startsWith("pal-") && f.endsWith(".instructions.md")
485
+ );
473
486
  }
474
487
 
475
488
  // ── Install integrity (Tier 2 doctor checks) ──
@@ -939,8 +952,8 @@ function doctor(silent = false): DoctorResult {
939
952
  ? ok("Copilot hooks registered")
940
953
  : fail("Copilot hooks — not registered (run 'pal cli install --copilot')");
941
954
  checkCopilotInstructionsPresent()
942
- ? ok("copilot-instructions.md present")
943
- : warn("copilot-instructions.md missing (run 'pal cli install --copilot')");
955
+ ? ok("Copilot instructions present")
956
+ : warn("Copilot instructions missing (written at first session stop)");
944
957
  }
945
958
  if (codex.available) {
946
959
  checkCodexHooksRegistered()