typeclaw 0.48.1 → 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.
- package/package.json +1 -1
- package/src/agent/index.ts +35 -9
- package/src/agent/plugin-tools.ts +14 -0
- package/src/agent/system-prompt.ts +8 -0
- package/src/agent/todo/continuation-policy.ts +11 -1
- package/src/agent/todo/continuation-state.ts +3 -1
- package/src/agent/todo/continuation-wiring.ts +2 -0
- package/src/agent/tool-file-safety.ts +7 -1
- package/src/agent/tools/channel-reply.ts +18 -1
- package/src/bundled-plugins/guard/policies/managed-config.ts +7 -20
- package/src/bundled-plugins/guard/policies/non-workspace-write.ts +7 -20
- package/src/bundled-plugins/guard/policies/skill-authoring.ts +8 -20
- package/src/bundled-plugins/memory/README.md +2 -0
- package/src/bundled-plugins/memory/dreaming.ts +2 -0
- package/src/bundled-plugins/security/policies/private-surface-read.ts +98 -55
- package/src/channels/adapters/discord-bot-reactions.ts +1 -0
- package/src/channels/adapters/discord-bot.ts +11 -2
- package/src/channels/adapters/discord-reactions.ts +1 -0
- package/src/channels/adapters/discord.ts +1 -0
- package/src/channels/adapters/slack-bot.ts +11 -2
- package/src/channels/adapters/slack.ts +1 -0
- package/src/channels/completion-claim.ts +307 -0
- package/src/channels/router.ts +275 -55
- package/src/channels/types.ts +4 -1
- package/src/config/providers.ts +100 -20
- package/src/container/start.ts +42 -0
- package/src/init/models-dev.ts +25 -8
- package/src/mcp/client.ts +65 -7
- package/src/mcp/tools.ts +71 -4
- package/src/path-safety/real-intended-path.ts +111 -0
- package/src/permissions/index.ts +1 -0
- package/src/permissions/permissions.ts +23 -0
- package/src/plugin/manager.ts +19 -1
- package/src/sandbox/canonical-secrets.ts +24 -4
- package/src/sandbox/hidden-paths.ts +8 -3
- package/src/sandbox/index.ts +2 -0
- package/src/skills/typeclaw-permissions/SKILL.md +13 -1
- package/src/skills/typeclaw-plugins/SKILL.md +91 -11
- package/typeclaw.schema.json +5 -0
|
@@ -99,6 +99,29 @@ export function findUnknownPermissions(
|
|
|
99
99
|
return out
|
|
100
100
|
}
|
|
101
101
|
|
|
102
|
+
// The mirror of findUnknownPermissions. `definePlugin({ permissions })`
|
|
103
|
+
// registers a string but grants nothing, so a plugin gating a surface on a
|
|
104
|
+
// fresh id without a matching `roles.<role>.permissions[]` entry is denied
|
|
105
|
+
// for EVERY caller including owner -- previously with no signal until the
|
|
106
|
+
// block fired at call time. Non-fatal: withholding a capability is a valid
|
|
107
|
+
// operator choice.
|
|
108
|
+
//
|
|
109
|
+
// Resolves the role table rather than reading raw config because
|
|
110
|
+
// expandOwnerWildcard auto-flows a plugin's `security.bypass.*` strings to
|
|
111
|
+
// owner; reading config would report every one of them as ungranted.
|
|
112
|
+
export function findUngrantedPluginPermissions(
|
|
113
|
+
roles: RolesConfig | undefined,
|
|
114
|
+
pluginPermissions: readonly string[],
|
|
115
|
+
ownerWildcardExclusions: readonly string[] = [],
|
|
116
|
+
): string[] {
|
|
117
|
+
if (pluginPermissions.length === 0) return []
|
|
118
|
+
const granted = new Set<string>()
|
|
119
|
+
for (const role of buildRoleTable(roles ?? {}, pluginPermissions, ownerWildcardExclusions)) {
|
|
120
|
+
for (const permission of role.permissions) granted.add(permission)
|
|
121
|
+
}
|
|
122
|
+
return pluginPermissions.filter((permission) => !granted.has(permission))
|
|
123
|
+
}
|
|
124
|
+
|
|
102
125
|
function closestPermission(target: string, known: ReadonlySet<string>): string {
|
|
103
126
|
let best: { name: string; distance: number } | null = null
|
|
104
127
|
for (const name of known) {
|
package/src/plugin/manager.ts
CHANGED
|
@@ -4,6 +4,7 @@ import type { ResolveGithubTokenForRepo } from '@/channels/github-token-bridge'
|
|
|
4
4
|
import type { CronJob } from '@/cron'
|
|
5
5
|
import {
|
|
6
6
|
createPermissionService,
|
|
7
|
+
findUngrantedPluginPermissions,
|
|
7
8
|
findUnknownPermissions,
|
|
8
9
|
type PermissionService,
|
|
9
10
|
type RolesConfig,
|
|
@@ -154,9 +155,10 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
|
|
|
154
155
|
// captured `permissions` by reference (their hooks read it at request time),
|
|
155
156
|
// so we mutate that same object in place rather than returning a new one.
|
|
156
157
|
const declaredPermissions = collectDeclaredPermissions(survivors)
|
|
158
|
+
const ownerWildcardExclusions = collectOwnerWildcardExclusions(survivors)
|
|
157
159
|
permissions.replacePluginPermissions?.({
|
|
158
160
|
pluginPermissions: declaredPermissions,
|
|
159
|
-
ownerWildcardExclusions
|
|
161
|
+
ownerWildcardExclusions,
|
|
160
162
|
})
|
|
161
163
|
|
|
162
164
|
// Non-fatal: surface user-declared `permissions[]` strings that aren't in
|
|
@@ -171,6 +173,22 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
|
|
|
171
173
|
)
|
|
172
174
|
}
|
|
173
175
|
|
|
176
|
+
// The opposite direction, and the one that silently ships dead code: the
|
|
177
|
+
// plugin declared a permission but no role grants it, so every surface
|
|
178
|
+
// gated on it is denied for all callers. Without this the only symptom is
|
|
179
|
+
// a `missing permission` block at call time, long after the boot that
|
|
180
|
+
// could have explained it.
|
|
181
|
+
for (const permission of findUngrantedPluginPermissions(opts.roles, declaredPermissions, ownerWildcardExclusions)) {
|
|
182
|
+
const declaredBy = survivors
|
|
183
|
+
.filter((p) => p.resolved.defined.permissions?.includes(permission))
|
|
184
|
+
.map((p) => p.resolved.name)
|
|
185
|
+
.join(', ')
|
|
186
|
+
console.warn(
|
|
187
|
+
`[permissions] plugin "${declaredBy}" declares "${permission}" but no role grants it — ` +
|
|
188
|
+
`every surface gated on it will be denied. Add it to roles.<role>.permissions[] in typeclaw.json and restart.`,
|
|
189
|
+
)
|
|
190
|
+
}
|
|
191
|
+
|
|
174
192
|
return {
|
|
175
193
|
registry,
|
|
176
194
|
hooks,
|
|
@@ -3,16 +3,36 @@ import {
|
|
|
3
3
|
LEGACY_AGENT_MESSENGER_CONFIG_RELATIVE_DIR,
|
|
4
4
|
} from '@/agent-messenger/config-dir'
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
6
|
+
// Runtime-owned credential stores: TypeClaw writes and reads these itself, and
|
|
7
|
+
// no shipped skill ever invokes a CLI that reads them. Masked at EVERY role.
|
|
8
|
+
export const RUNTIME_OWNED_SECRET_DIRS = [
|
|
9
9
|
// Retained permanently for interrupted migrations, operator backups under
|
|
10
|
-
// the old name, and older installs. This is not an active config location
|
|
10
|
+
// the old name, and older installs. This is not an active config location,
|
|
11
|
+
// so nothing an operator provisions today lands here.
|
|
11
12
|
LEGACY_AGENT_MESSENGER_CONFIG_RELATIVE_DIR,
|
|
12
13
|
'.typeclaw/home',
|
|
13
14
|
'.typeclaw/logs',
|
|
14
15
|
] as const
|
|
15
16
|
|
|
17
|
+
// SECURITY / classification: operator-provisioned CLI credential stores. TypeClaw
|
|
18
|
+
// writes these through its own init/auth flows and points the matching CLI at them
|
|
19
|
+
// (`dockerfile.ts` bakes `ENV AGENT_MESSENGER_CONFIG_DIR`), so the agent is MEANT
|
|
20
|
+
// to read them — the bundled `agent-*` and gws skills shell out to CLIs that
|
|
21
|
+
// resolve exactly these files. Masking them at every role does not withhold a
|
|
22
|
+
// secret, it breaks the skill and leaves the CLI reporting its own "not
|
|
23
|
+
// authenticated", which a model relays as a fact about the upstream service.
|
|
24
|
+
//
|
|
25
|
+
// So they take the ordinary private-surface role gate, which is what applied to
|
|
26
|
+
// them before they were named here (they live under `workspace/`). Add a path
|
|
27
|
+
// here only if a shipped skill needs to read it; anything that must stay hidden
|
|
28
|
+
// from every role belongs in `secrets.json`, not in a masked directory.
|
|
29
|
+
export const OPERATOR_CLI_CREDENTIAL_DIRS = ['workspace/.config/gws', AGENT_MESSENGER_CONFIG_RELATIVE_DIR] as const
|
|
30
|
+
|
|
31
|
+
// Union: every directory that is masked for SOME role. Consumers that need the
|
|
32
|
+
// full set regardless of gating (write-zone vetoes, hardlink-alias scanning)
|
|
33
|
+
// use this; consumers that must respect the gate read the two lists above.
|
|
34
|
+
export const CANONICAL_AGENT_SECRET_DIRS = [...OPERATOR_CLI_CREDENTIAL_DIRS, ...RUNTIME_OWNED_SECRET_DIRS] as const
|
|
35
|
+
|
|
16
36
|
export const CANONICAL_AGENT_SECRET_FILES = ['.env', 'secrets.json', 'auth.json'] as const
|
|
17
37
|
|
|
18
38
|
// Trusted runtime processes use this ephemeral container HOME. bwrap builds an
|
|
@@ -5,7 +5,12 @@ import type { SessionOrigin } from '@/agent/session-origin'
|
|
|
5
5
|
import { CORE_PERMISSIONS } from '@/permissions/builtins'
|
|
6
6
|
import type { PermissionService } from '@/permissions/permissions'
|
|
7
7
|
|
|
8
|
-
import {
|
|
8
|
+
import {
|
|
9
|
+
CANONICAL_AGENT_SECRET_DIRS,
|
|
10
|
+
CANONICAL_AGENT_SECRET_FILES,
|
|
11
|
+
OPERATOR_CLI_CREDENTIAL_DIRS,
|
|
12
|
+
RUNTIME_OWNED_SECRET_DIRS,
|
|
13
|
+
} from './canonical-secrets'
|
|
9
14
|
import { SandboxMaskTargetError } from './errors'
|
|
10
15
|
import { CANONICAL_AGENT_RUNTIME_PRIVATE_FILES } from './runtime-private'
|
|
11
16
|
|
|
@@ -36,8 +41,8 @@ export function resolveHiddenPaths(
|
|
|
36
41
|
): HiddenPaths {
|
|
37
42
|
const seesPrivate = canSeePrivateSurface(permissions, origin)
|
|
38
43
|
const dirs = [
|
|
39
|
-
...
|
|
40
|
-
...(seesPrivate ? [] : PRIVATE_DIRS.map((dir) => join(agentDir, dir))),
|
|
44
|
+
...RUNTIME_OWNED_SECRET_DIRS.map((dir) => join(agentDir, dir)),
|
|
45
|
+
...(seesPrivate ? [] : [...OPERATOR_CLI_CREDENTIAL_DIRS, ...PRIVATE_DIRS].map((dir) => join(agentDir, dir))),
|
|
41
46
|
]
|
|
42
47
|
const files = [...CANONICAL_AGENT_SECRET_FILES, ...CANONICAL_AGENT_RUNTIME_PRIVATE_FILES].map((f) =>
|
|
43
48
|
join(agentDir, f),
|
package/src/sandbox/index.ts
CHANGED
|
@@ -5,6 +5,8 @@ export {
|
|
|
5
5
|
CANONICAL_HOME_SECRET_DIRS,
|
|
6
6
|
CANONICAL_HOME_SECRET_FILES,
|
|
7
7
|
CONTAINER_RUNTIME_HOME,
|
|
8
|
+
OPERATOR_CLI_CREDENTIAL_DIRS,
|
|
9
|
+
RUNTIME_OWNED_SECRET_DIRS,
|
|
8
10
|
} from './canonical-secrets'
|
|
9
11
|
export { CANONICAL_AGENT_RUNTIME_PRIVATE_FILES } from './runtime-private'
|
|
10
12
|
export {
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: typeclaw-permissions
|
|
3
|
-
description: Use this skill whenever the user asks who you talk to, why you went silent in a channel, why a tool call was blocked with `blocked:` / "denied by permissions", how to grant access, what a role can or can't do, or whenever you are about to edit the `roles` block in `typeclaw.json`. Triggers include "who can talk to you", "why aren't you replying in #channel", "add me to the agent", "let X talk to you", "grant trusted to Y", "your role", "what permissions do you have", "blocked", "denied by permissions", "owner", "trusted", "member", "guest", "match rule", "channel.respond", "security.bypass", "scheduledByRole", "spawnedByRole", or any mention of `roles` / `roles[*].match` / `roles[*].permissions` in `typeclaw.json`. Read it before editing `roles` — the file has a strict match-rule DSL, restart semantics, and silent failure modes (a missing role match makes you silently drop every inbound), and the agent's own runtime behavior depends on its role and resolved permissions.
|
|
3
|
+
description: Use this skill whenever the user asks who you talk to, why you went silent in a channel, why a tool call was blocked with `blocked:` / "denied by permissions", how to grant access, what a role can or can't do, or whenever you are about to edit the `roles` block in `typeclaw.json`. Triggers include "who can talk to you", "why aren't you replying in #channel", "add me to the agent", "let X talk to you", "grant trusted to Y", "your role", "what permissions do you have", "blocked", "denied by permissions", "owner", "trusted", "member", "guest", "match rule", "channel.respond", "security.bypass", "scheduledByRole", "spawnedByRole", "missing permission", "plugin permission", "always denied", or any mention of `roles` / `roles[*].match` / `roles[*].permissions` in `typeclaw.json`. Read it before editing `roles` — the file has a strict match-rule DSL, restart semantics, and silent failure modes (a missing role match makes you silently drop every inbound), and the agent's own runtime behavior depends on its role and resolved permissions.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# typeclaw-permissions
|
|
@@ -134,6 +134,18 @@ Note on the two-step `gitRemoteTainted` defense: trusted bypasses `gitExfil` via
|
|
|
134
134
|
|
|
135
135
|
User-declared `permissions[]` strings that don't appear in any of the three sources are **logged as warnings at boot** (`[permissions] role "X" declares unknown permission "Y" — did you mean 'Z'?`) but the role still resolves with the unknown string in its list. This is intentional — the runtime is forward-compatible with strings from plugins that aren't loaded yet — but it also means typos silently fail to bypass guards. If you wrote `security.bypass.secretExfilBach` instead of `Bash`, no guard will be skipped and you will only notice when you read the boot logs.
|
|
136
136
|
|
|
137
|
+
### The mirror failure: a plugin permission no role grants
|
|
138
|
+
|
|
139
|
+
The typo case above is a role naming a permission that doesn't exist. The opposite also happens: a plugin declares a permission via `definePlugin({ permissions: [...] })` (see `typeclaw-plugins`), but no role's `permissions[]` in `typeclaw.json` ever lists it. Declaring a permission only registers the string into the known-permission universe — it does not grant it. The only strings that auto-flow to a role are `security.bypass.*` ones, and only to `owner`, via the wildcard sentinel. Every other plugin-declared string starts out held by **nobody** — not owner, not trusted, not member, not guest.
|
|
140
|
+
|
|
141
|
+
**Symptom**: a plugin tool or command fails every call, for every user including owner, with a message naming the id — `missing permission: <id>`, or a `blocked:` reason citing it. Unlike a security-guard block, there's no acknowledgement and no role that already has it to fall back to; the string simply isn't granted anywhere.
|
|
142
|
+
|
|
143
|
+
**Boot signal**: `[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.`
|
|
144
|
+
|
|
145
|
+
**Fix**: add the exact string to `roles.<role>.permissions[]` and restart — same restart-required rule as every other `permissions[]` edit in this file. If `<role>` is a built-in (`owner`/`trusted`/`member`), remember an explicit `permissions[]` replaces that role's default list wholesale (see the table above); re-list the role's full default set alongside the new string, or the role silently loses `channel.respond` and everything else.
|
|
146
|
+
|
|
147
|
+
See `typeclaw-plugins` for the authoring side of this — declaring and gating on a permission is a two-part recipe, and shipping the declaration without the grant leaves a surface that looks wired but is dead.
|
|
148
|
+
|
|
137
149
|
## When a tool is blocked
|
|
138
150
|
|
|
139
151
|
The security plugin's `tool.before` hook produces block messages. For most guards the message is:
|
|
@@ -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: [...]`
|
|
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
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
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
|
-
|
|
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: ['
|
|
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,
|
package/typeclaw.schema.json
CHANGED
|
@@ -57,6 +57,7 @@
|
|
|
57
57
|
"minimax/MiniMax-M2",
|
|
58
58
|
"deepseek/deepseek-v4-flash",
|
|
59
59
|
"deepseek/deepseek-v4-pro",
|
|
60
|
+
"upstage/solar-pro4",
|
|
60
61
|
"upstage/solar-open2",
|
|
61
62
|
"upstage/solar-pro3",
|
|
62
63
|
"upstage/solar-pro2",
|
|
@@ -114,6 +115,7 @@
|
|
|
114
115
|
"minimax/MiniMax-M2",
|
|
115
116
|
"deepseek/deepseek-v4-flash",
|
|
116
117
|
"deepseek/deepseek-v4-pro",
|
|
118
|
+
"upstage/solar-pro4",
|
|
117
119
|
"upstage/solar-open2",
|
|
118
120
|
"upstage/solar-pro3",
|
|
119
121
|
"upstage/solar-pro2",
|
|
@@ -172,6 +174,7 @@
|
|
|
172
174
|
"minimax/MiniMax-M2",
|
|
173
175
|
"deepseek/deepseek-v4-flash",
|
|
174
176
|
"deepseek/deepseek-v4-pro",
|
|
177
|
+
"upstage/solar-pro4",
|
|
175
178
|
"upstage/solar-open2",
|
|
176
179
|
"upstage/solar-pro3",
|
|
177
180
|
"upstage/solar-pro2",
|
|
@@ -228,6 +231,7 @@
|
|
|
228
231
|
"minimax/MiniMax-M2",
|
|
229
232
|
"deepseek/deepseek-v4-flash",
|
|
230
233
|
"deepseek/deepseek-v4-pro",
|
|
234
|
+
"upstage/solar-pro4",
|
|
231
235
|
"upstage/solar-open2",
|
|
232
236
|
"upstage/solar-pro3",
|
|
233
237
|
"upstage/solar-pro2",
|
|
@@ -285,6 +289,7 @@
|
|
|
285
289
|
"minimax/MiniMax-M2",
|
|
286
290
|
"deepseek/deepseek-v4-flash",
|
|
287
291
|
"deepseek/deepseek-v4-pro",
|
|
292
|
+
"upstage/solar-pro4",
|
|
288
293
|
"upstage/solar-open2",
|
|
289
294
|
"upstage/solar-pro3",
|
|
290
295
|
"upstage/solar-pro2",
|