typeclaw 0.48.2 → 0.48.3

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.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: typeclaw-plugins
3
- description: TypeClaw plugin authoring and operation guide. Use when writing, editing, configuring, debugging, or installing a TypeClaw plugin — including any work with definePlugin, defineTool, defineSubagent, plugin hooks (session.start/end/idle/prompt, tool.before/after), plugin cron jobs, plugin commands (host/container/either CLI subcommands callable as `typeclaw <name>`), plugin skills, the typeclaw/plugin import path, or per-plugin config blocks in typeclaw.json. Also use when you need to bridge a cron `exec` job to LLM-driven work — the canonical pattern is a `surface: 'container'` plugin command whose `run` calls `ctx.prompt(...)`, invoked as `typeclaw <command>` from cron's `command` array. Triggers on mentions of 'TypeClaw plugin', 'definePlugin', 'plugin hook', 'plugin cron', 'plugin command', 'PluginCommand', 'ContainerCommand', 'HostCommand', 'EitherCommand', 'ctx.prompt', 'ctx.subagent', 'ctx.exec', 'plugins[]', 'typeclaw-plugin-', or any file under src/plugin/ or plugins/.
3
+ description: TypeClaw plugin authoring and operation guide. Use when writing, editing, configuring, debugging, or installing a TypeClaw plugin — including any work with definePlugin, defineTool, defineSubagent, plugin hooks (session.start/end/idle/prompt, tool.before/after), plugin cron jobs, plugin commands (host/container/either CLI subcommands callable as `typeclaw <name>`), plugin skills, the typeclaw/plugin import path, or per-plugin config blocks in typeclaw.json. Also use when you need to bridge a cron `exec` job to LLM-driven work — the canonical pattern is a `surface: 'container'` plugin command whose `run` calls `ctx.prompt(...)`, invoked as `typeclaw <command>` from cron's `command` array. Triggers on mentions of 'TypeClaw plugin', 'definePlugin', 'plugin hook', 'plugin cron', 'plugin command', 'PluginCommand', 'ContainerCommand', 'HostCommand', 'EitherCommand', 'ctx.prompt', 'ctx.subagent', 'ctx.exec', 'plugins[]', 'typeclaw-plugin-', 'plugin permission', 'definePlugin permissions', 'missing permission', 'permission-gated tool', or any file under src/plugin/ or plugins/.
4
4
  ---
5
5
 
6
6
  # TypeClaw Plugins
@@ -203,6 +203,7 @@ tools: {
203
203
  - Args are **validated once** before `tool.before` hooks see them — no double-parse. Hooks receive `event.args` as a **mutable bag** (`Record<string, unknown>`); mutations propagate to later hooks and to `execute`.
204
204
  - `ToolContext` is **stripped down** to `{ signal, sessionId, agentDir, logger }`. It does NOT expose the engine's `ExtensionContext`. If your tool wants `read`/`bash`/etc., it cannot call them — declare a subagent with `tools: [readTool, ...]` instead.
205
205
  - `ToolResult.content` uses TypeClaw's `ContentPart` union: `{ type: 'text'; text }` or `{ type: 'image'; mimeType; data }`.
206
+ - Tools have **no `permissions` field**. To gate one per role, declare the string on the plugin and block from a `tool.before` hook — and grant it in `typeclaw.json`, or the tool is dead for every caller. See "`permissions: [...]` — declaring and gating" in §5.7.
206
207
 
207
208
  #### Declare every filesystem operand
208
209
 
@@ -330,7 +331,7 @@ type CronHandlerContext = {
330
331
  readonly agentDir: string // /agent in container
331
332
  readonly logger: PluginLogger
332
333
  readonly signal: AbortSignal // reserved for future cancellation; currently inert
333
- readonly permissions: PermissionService
334
+ readonly permissions: PermissionService // live service — has() gating, see "permissions: [...] — declaring and gating" in §5.7 below
334
335
  readonly origin: SessionOrigin // { kind: 'cron', jobKind: 'handler', ... }
335
336
  readonly prompt: (text: string) => Promise<string> // full agent session, slim system prompt mode
336
337
  readonly subagent: (name, payload?) => Promise<void>
@@ -481,7 +482,7 @@ type ContainerCommandContext = {
481
482
  readonly version: string | undefined
482
483
  readonly agentDir: string // /agent inside the container
483
484
  readonly logger: PluginLogger
484
- readonly permissions: PermissionService
485
+ readonly permissions: PermissionService // live service — has() gating, see "permissions: [...] — declaring and gating" below
485
486
  readonly origin: SessionOrigin // caller's origin — cron job, TUI op, etc.
486
487
  readonly signal: AbortSignal // aborts on ws close or host Ctrl-C
487
488
  readonly stdin: ReadableStream<Uint8Array>
@@ -579,20 +580,98 @@ args: z.object({
579
580
  - `.describe(...)` populates `--help` output. Use it.
580
581
  - Omit `args` entirely if the command takes no flags.
581
582
 
582
- #### `permissions: [...]` on the command
583
+ #### `permissions: [...]` — declaring and gating
584
+
585
+ **Declaring a permission grants it to nobody.** `definePlugin({ permissions: [...] })` only registers the string into the known-permission universe — used for the boot-time typo warning and, for `security.bypass.*` strings only, owner-wildcard expansion. Every other permission string starts out held by no role: not owner, not trusted, not member, not guest. A plugin that gates a command or tool on a permission and never adds that string to any `roles.<role>.permissions[]` in `typeclaw.json` has shipped a permanently blocked surface — declaring is half the work, granting is the other half. Never ship one without the other.
586
+
587
+ **`definePlugin({ permissions })` is the only declaration that does anything.** `ContainerCommand.permissions` exists in the type but no production path reads it — it is not rendered in `--help` (`renderCommandHelp` prints description, plugin, surface, options), not collected into the known-permission universe (`collectDeclaredPermissions` reads only the plugin-level list), and never checked for you. Declare at the plugin level. Setting it on a command instead is worse than useless: the string stays outside the known universe, so granting it in a role also trips the `unknown permission` typo warning at boot.
588
+
589
+ **Gating a command** — declare the string on the plugin, then check it inside `run`:
583
590
 
584
591
  ```ts
592
+ const WRITE_PERMISSION = 'standup.write.entry'
593
+
594
+ export default definePlugin({
595
+ permissions: [WRITE_PERMISSION],
596
+ commands: {
597
+ standup: {
598
+ surface: 'container',
599
+ description: 'Append a standup entry.',
600
+ async run(ctx, args) {
601
+ if (!ctx.permissions.has(ctx.origin, WRITE_PERMISSION)) {
602
+ const writer = ctx.stderr.getWriter()
603
+ await writer.write(new TextEncoder().encode(`missing permission: ${WRITE_PERMISSION}\n`))
604
+ writer.releaseLock()
605
+ return 1
606
+ }
607
+ // ...
608
+ return 0
609
+ },
610
+ },
611
+ },
612
+ plugin: async () => ({}),
613
+ })
614
+ ```
615
+
616
+ ```jsonc
617
+ // typeclaw.json — the grant this declaration needs, or the command always fails
585
618
  {
586
- surface: 'container',
587
- permissions: ['standup-log.write.standup'],
588
- async run(ctx, args) {
589
- ctx.permissions.assert(ctx.origin, 'standup-log.write.standup')
590
- // ...
619
+ "roles": {
620
+ "trusted": {
621
+ "permissions": ["standup.write.entry" /* ...trusted's full default list too, see below */],
622
+ },
591
623
  },
592
624
  }
593
625
  ```
594
626
 
595
- Declared permissions are surfaced in `--help` and (for container commands) checked against the caller's origin. Same `<plugin>.<verb>.<noun>` shape as the rest of the permission system; see `typeclaw-permissions`.
627
+ `PermissionService` exposes `has(origin, permission)` — a boolean. **There is no `assert`.** Nothing authorizes on your behalf: `has` resolves the caller's origin to a role and returns false unless that role's permission list contains the exact string, and it is on you to fail the call. Same `<plugin>.<verb>.<noun>` shape as the rest of the permission system; see `typeclaw-permissions`.
628
+
629
+ **Permission ids cannot contain hyphens.** `roles[].permissions[]` validates against `^[a-z][a-z0-9]*(\.[a-z][a-zA-Z0-9]*)+$` — dot-separated segments, each starting lowercase, alphanumeric after (camelCase is fine, `-` is not). Nothing validates the `definePlugin({ permissions })` side, so a hyphenated id like `standup-log.write.entry` declares happily and then **cannot be granted at all**: the config edit fails schema validation. A hyphenated plugin name needs a hyphen-free permission namespace — plugin `standup-log` uses `standup.write.entry`.
630
+
631
+ **Gating a tool** — tools have no `permissions` field of their own; gate them from a `tool.before` hook with `pluginContext.permissions.has(event.origin, ...)`:
632
+
633
+ ```ts
634
+ const PUBLISH_PERMISSION = 'standup.publish.remote'
635
+
636
+ export default definePlugin({
637
+ permissions: [PUBLISH_PERMISSION],
638
+ plugin: async (pluginContext) => ({
639
+ tools: {
640
+ standup_publish: defineTool({
641
+ /* ... */
642
+ }),
643
+ },
644
+ hooks: {
645
+ 'tool.before': (event) => {
646
+ if (event.tool !== 'standup_publish') return
647
+ if (pluginContext.permissions.has(event.origin, PUBLISH_PERMISSION)) return
648
+ return { block: true, reason: `missing permission: ${PUBLISH_PERMISSION}` }
649
+ },
650
+ },
651
+ }),
652
+ })
653
+ ```
654
+
655
+ ```jsonc
656
+ // typeclaw.json — same recipe: declaring PUBLISH_PERMISSION above grants nothing on its own
657
+ {
658
+ "roles": {
659
+ "trusted": {
660
+ "permissions": ["standup.publish.remote" /* ...trusted's full default list too, see below */],
661
+ },
662
+ },
663
+ }
664
+ ```
665
+
666
+ Omit that second half and the failure is silent and total: the plugin compiles, boots, and registers the tool, but every call — including from `owner` — is blocked forever, because nothing ever granted the string. The tool looks wired and is dead.
667
+
668
+ **Built-in roles: an explicit `permissions[]` REPLACES the default, it does not add to it.** Add your string to `roles.owner.permissions[]` and you must re-list `owner`'s entire default permission set alongside it, including the `security.bypass.*` strings the wildcard sentinel would otherwise expand for you (the sentinel is an internal runtime value — you cannot write it, and the schema rejects it). Don't copy the default lists from memory; read `typeclaw-permissions` for the current per-role defaults.
669
+
670
+ **Restart required.** `roles.<role>.permissions[]` is a `restart-required` field — `typeclaw reload` will not pick up a new grant. `roles.<role>.match[]` is live-reloadable; permissions are not. Run `typeclaw restart`.
671
+
672
+ **The boot-time signal for a forgotten grant**: `[permissions] plugin "<name>" declares "<id>" but no role grants it — every surface gated on it will be denied. Add it to roles.<role>.permissions[] in typeclaw.json and restart.` If you see this at boot, or a tool/command you just wired is blocked for every caller including yourself, this is why.
673
+
674
+ **When NOT to declare a permission.** If your plugin is the only caller of the surface it gates — no operator will ever want to withhold or grant this capability per role — the check is just an `if (false)` with extra steps. Declare a permission only when you actually want an operator able to grant or withhold it per role.
596
675
 
597
676
  #### `isolated: true` (container surface only)
598
677
 
@@ -631,6 +710,7 @@ type PluginContext<TConfig = never> = {
631
710
  readonly agentDir: string // absolute, agent folder root
632
711
  readonly config: TConfig // inferred from configSchema
633
712
  readonly logger: PluginLogger // prefixed: [plugin:<name>]
713
+ readonly permissions: PermissionService // live service — has() gating, see "permissions: [...] — declaring and gating" in §5.7 above
634
714
  spawnSubagent: (name: string, payload?: unknown) => Promise<void>
635
715
  }
636
716
  ```
@@ -872,7 +952,7 @@ export default definePlugin({
872
952
  commands: {
873
953
  /* name: { surface, run, args?, ... } */
874
954
  }, // optional, declared BY-VALUE (not inside factory)
875
- permissions: ['my-plugin.write.x'], // optional
955
+ permissions: ['myplugin.write.x'], // optional; declares only — grant it in roles.<role>.permissions[] in typeclaw.json or nobody has it
876
956
  plugin: async (ctx) => ({
877
957
  // required
878
958
  tools,