typeclaw 0.39.3 → 0.39.4
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 +10 -14
- package/src/agent/model-fallback.ts +13 -4
- package/src/agent/provider-error.ts +36 -1
- package/src/agent/subagents.ts +29 -2
- package/src/agent/throttle-circuit.ts +50 -0
- package/src/agent/turn-runner.ts +162 -0
- package/src/bundled-plugins/memory/README.md +12 -12
- package/src/bundled-plugins/memory/append-tool.ts +58 -6
- package/src/bundled-plugins/memory/dreaming.ts +1 -1
- package/src/bundled-plugins/memory/fragment-parser.ts +10 -3
- package/src/bundled-plugins/memory/load-memory.ts +28 -2
- package/src/bundled-plugins/memory/memory-logger.ts +14 -2
- package/src/bundled-plugins/memory/search-tool.ts +50 -7
- package/src/bundled-plugins/memory/stream-events.ts +23 -0
- package/src/bundled-plugins/memory/vector/hybrid.ts +9 -2
- package/src/bundled-plugins/security/index.ts +24 -1
- package/src/bundled-plugins/security/policies/cron-promotion.ts +94 -62
- package/src/bundled-plugins/security/policies/plugin-addition.ts +2 -4
- package/src/bundled-plugins/security/policies/role-promotion.ts +2 -4
- package/src/channels/adapters/webex-bot.ts +26 -25
- package/src/channels/adapters/webex-prefetch-limiter.ts +120 -0
- package/src/channels/adapters/webex.ts +27 -30
- package/src/channels/manager.ts +64 -57
- package/src/channels/router.ts +134 -4
- package/src/channels/types.ts +8 -1
- package/src/cli/builtins.ts +6 -32
- package/src/cli/command-meta.ts +93 -0
- package/src/cli/help.ts +24 -0
- package/src/cli/index.ts +34 -10
- package/src/config/config.ts +27 -1
- package/src/container/start.ts +22 -2
- package/src/hostd/daemon.ts +55 -26
- package/src/hostd/spawn.ts +53 -19
- package/src/permissions/permissions.ts +12 -0
- package/src/run/codex-fetch-observer.ts +11 -6
- package/src/secrets/oauth-xai.ts +2 -2
- package/src/server/index.ts +27 -2
- package/src/skills/typeclaw-channels/SKILL.md +1 -1
- package/src/skills/typeclaw-config/SKILL.md +1 -0
- package/src/skills/typeclaw-cron/SKILL.md +9 -4
- package/src/skills/typeclaw-permissions/SKILL.md +18 -6
package/src/cli/index.ts
CHANGED
|
@@ -75,6 +75,17 @@ function runHostStartupMigrationsOnce(commandName: string | undefined): void {
|
|
|
75
75
|
}
|
|
76
76
|
}
|
|
77
77
|
|
|
78
|
+
// Plugin commands are discovered from the agent folder; outside one, discovery
|
|
79
|
+
// yields nothing and no section prints. Shared by the --help and no-command
|
|
80
|
+
// paths so both keep showing plugin commands above the builtin usage table.
|
|
81
|
+
async function printPluginCommandsSection(): Promise<void> {
|
|
82
|
+
const { renderPluginCommandsSection } = await import('./plugin-command-help')
|
|
83
|
+
const { discoverCommands } = await import('./plugin-commands')
|
|
84
|
+
const discovery = await discoverCommands({ cwd: process.cwd() })
|
|
85
|
+
const section = renderPluginCommandsSection(discovery.commands)
|
|
86
|
+
if (section !== null) process.stdout.write(`${section}\n\n`)
|
|
87
|
+
}
|
|
88
|
+
|
|
78
89
|
async function runWithPluginDispatch(): Promise<void> {
|
|
79
90
|
const argv = process.argv.slice(2)
|
|
80
91
|
const first = argv[0]
|
|
@@ -91,17 +102,30 @@ async function runWithPluginDispatch(): Promise<void> {
|
|
|
91
102
|
await maybeNotifyUpdate(first)
|
|
92
103
|
}
|
|
93
104
|
|
|
105
|
+
// Top-level help and the no-command case are hand-rendered from the static
|
|
106
|
+
// command-meta table (see ./help) instead of `runMain(main)`. Routing them
|
|
107
|
+
// through citty would resolve every lazy `subCommands` thunk just to read the
|
|
108
|
+
// descriptions for the usage table, importing all 25 command modules (and
|
|
109
|
+
// their config/docker/agent-messenger graphs) — which made a bare `typeclaw`
|
|
110
|
+
// slower than running a real subcommand. Per-command help (`typeclaw x --help`)
|
|
111
|
+
// still goes through citty below, importing only that one command.
|
|
94
112
|
if (first === '--help' || first === '-h') {
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
113
|
+
await printPluginCommandsSection()
|
|
114
|
+
const { renderTopLevelUsage } = await import('./help')
|
|
115
|
+
process.stdout.write(`${await renderTopLevelUsage()}\n\n`)
|
|
116
|
+
process.exit(0)
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
if (first === undefined) {
|
|
120
|
+
// No plugin discovery here: bare `typeclaw` must stay a pure
|
|
121
|
+
// E_NO_COMMAND report and never load plugin/config code (discoverCommands
|
|
122
|
+
// can rewrite typeclaw.json via loadConfigSync). Plugin commands surface
|
|
123
|
+
// only on explicit top-level help and plugin-command dispatch. Mirror
|
|
124
|
+
// citty's E_NO_COMMAND: usage to stdout, the message to stderr, exit 1.
|
|
125
|
+
const { renderTopLevelUsage } = await import('./help')
|
|
126
|
+
process.stdout.write(`${await renderTopLevelUsage()}\n\n`)
|
|
127
|
+
process.stderr.write('No command specified.\n')
|
|
128
|
+
process.exit(1)
|
|
105
129
|
}
|
|
106
130
|
|
|
107
131
|
if (
|
package/src/config/config.ts
CHANGED
|
@@ -707,13 +707,39 @@ const profileEntrySchema = z
|
|
|
707
707
|
return value.thinkingLevel === undefined ? { refs } : { refs, thinkingLevel: value.thinkingLevel }
|
|
708
708
|
})
|
|
709
709
|
|
|
710
|
+
// Built-in per-profile `thinkingLevel` defaults, materialized at parse time so
|
|
711
|
+
// resolved config / `typeclaw model list` / prompt dumps show the effective level
|
|
712
|
+
// and users can override per profile. Materialized here (not as a runtime
|
|
713
|
+
// constant) the `deep: 'high'` default rides on the `deep` entry itself, so it
|
|
714
|
+
// still beats a lowered `models.default.thinkingLevel` (resolution reads the
|
|
715
|
+
// profile's own level first). `default` and `vision` carry none — they fall
|
|
716
|
+
// through to the model/SDK default. `high` over `xhigh`: `xhigh` ~doubles latency
|
|
717
|
+
// and spend for no agentic-quality gain.
|
|
718
|
+
const PROFILE_THINKING_LEVEL_DEFAULTS = {
|
|
719
|
+
fast: 'low',
|
|
720
|
+
deep: 'high',
|
|
721
|
+
} satisfies Partial<Record<string, ThinkingLevel>>
|
|
722
|
+
|
|
710
723
|
export const modelsSchema = z
|
|
711
724
|
.record(z.string().min(1), profileEntrySchema)
|
|
712
725
|
.refine((m) => 'default' in m, { message: 'models.default is required' })
|
|
726
|
+
// Fill only when unset, so an explicit level (including `off`) always wins.
|
|
727
|
+
.transform((models): Models => {
|
|
728
|
+
let next: Record<string, ProfileEntry> | undefined
|
|
729
|
+
for (const [profile, thinkingLevel] of Object.entries(PROFILE_THINKING_LEVEL_DEFAULTS)) {
|
|
730
|
+
const entry = models[profile]
|
|
731
|
+
if (entry !== undefined && entry.thinkingLevel === undefined) {
|
|
732
|
+
next ??= { ...models }
|
|
733
|
+
next[profile] = { ...entry, thinkingLevel }
|
|
734
|
+
}
|
|
735
|
+
}
|
|
736
|
+
return (next ?? models) as Models
|
|
737
|
+
})
|
|
713
738
|
|
|
714
739
|
// A model profile after normalisation: its fallback chain (always non-empty)
|
|
715
740
|
// plus an optional reasoning effort. `thinkingLevel` resolution is layered at
|
|
716
|
-
// session creation: profile's own
|
|
741
|
+
// session creation: profile's own (incl. built-in per-profile defaults
|
|
742
|
+
// materialized above) → `default` profile's → SDK default.
|
|
717
743
|
export type ProfileEntry = {
|
|
718
744
|
refs: ModelRef[]
|
|
719
745
|
thinkingLevel?: ThinkingLevel
|
package/src/container/start.ts
CHANGED
|
@@ -12,7 +12,7 @@ import { send as sendToDaemon } from '@/hostd/client'
|
|
|
12
12
|
import { ensureModels } from '@/hostd/models'
|
|
13
13
|
import { homeRoot } from '@/hostd/paths'
|
|
14
14
|
import type { HttpInfoResult } from '@/hostd/protocol'
|
|
15
|
-
import { ensureDaemon } from '@/hostd/spawn'
|
|
15
|
+
import { ensureDaemon, type EnsureDaemonResult } from '@/hostd/spawn'
|
|
16
16
|
import {
|
|
17
17
|
autoUpgradeTypeclawDep,
|
|
18
18
|
type AutoUpgradeOutcome,
|
|
@@ -1165,7 +1165,7 @@ async function registerWithDaemon({
|
|
|
1165
1165
|
hostPort: number
|
|
1166
1166
|
reuseCurrentHostDaemon: boolean
|
|
1167
1167
|
}): Promise<PreparedHostDaemonStatus> {
|
|
1168
|
-
const prepared = reuseCurrentHostDaemon ? await useCurrentHostDaemon() : await
|
|
1168
|
+
const prepared = reuseCurrentHostDaemon ? await useCurrentHostDaemon() : await ensureDaemonWithBridgeRetry(cliEntry)
|
|
1169
1169
|
if (!prepared.ok) return { state: 'unavailable', reason: prepared.reason }
|
|
1170
1170
|
const token = randomBytes(32).toString('base64url')
|
|
1171
1171
|
const brokerToken = randomBytes(32).toString('base64url')
|
|
@@ -1186,6 +1186,26 @@ async function registerWithDaemon({
|
|
|
1186
1186
|
}
|
|
1187
1187
|
}
|
|
1188
1188
|
|
|
1189
|
+
// ensureDaemon spawns the daemon detached and polls for readiness, but a cold
|
|
1190
|
+
// daemon can take longer than that internal window to bind its socket. Rather
|
|
1191
|
+
// than treat the first not-ready-yet as a hard failure (which would drop the
|
|
1192
|
+
// hostd env vars and crash hostd-backed channel adapters on boot), re-probe a
|
|
1193
|
+
// few times: the still-booting daemon becomes reachable and ensureDaemon
|
|
1194
|
+
// fast-paths through its top-of-function isDaemonReachable() check WITHOUT
|
|
1195
|
+
// re-spawning. Bridges the first-boot spawn race; a genuinely dead daemon still
|
|
1196
|
+
// surfaces as unavailable after the budget.
|
|
1197
|
+
const HOSTD_BRIDGE_RETRIES = 3
|
|
1198
|
+
const HOSTD_BRIDGE_RETRY_DELAY_MS = 2_000
|
|
1199
|
+
|
|
1200
|
+
async function ensureDaemonWithBridgeRetry(cliEntry: string): Promise<EnsureDaemonResult> {
|
|
1201
|
+
let last = await ensureDaemon({ cliEntry })
|
|
1202
|
+
for (let attempt = 0; !last.ok && attempt < HOSTD_BRIDGE_RETRIES; attempt++) {
|
|
1203
|
+
await new Promise((resolve) => setTimeout(resolve, HOSTD_BRIDGE_RETRY_DELAY_MS))
|
|
1204
|
+
last = await ensureDaemon({ cliEntry })
|
|
1205
|
+
}
|
|
1206
|
+
return last
|
|
1207
|
+
}
|
|
1208
|
+
|
|
1189
1209
|
async function useCurrentHostDaemon(): Promise<{ ok: true; httpPort: number } | { ok: false; reason: string }> {
|
|
1190
1210
|
const reply = await sendToDaemon({ kind: 'http-info' })
|
|
1191
1211
|
if (!reply.ok) return { ok: false, reason: reply.reason }
|
package/src/hostd/daemon.ts
CHANGED
|
@@ -285,6 +285,12 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
|
|
|
285
285
|
const gcMisses = new Map<string, number>()
|
|
286
286
|
let stopped = false
|
|
287
287
|
let httpPort = 0
|
|
288
|
+
// Boot-time restore runs concurrently with the listeners (see the kickoff
|
|
289
|
+
// below). Declared here so the IPC dispatcher and HTTP handler — both defined
|
|
290
|
+
// before restore starts — can gate on it; until it's assigned, no registry
|
|
291
|
+
// RPC has been accepted yet, so resolving immediately is safe.
|
|
292
|
+
let restoreComplete: Promise<void> | null = null
|
|
293
|
+
const awaitRestored = (): Promise<void> => restoreComplete ?? Promise.resolve()
|
|
288
294
|
|
|
289
295
|
const supervisor = opts.restart
|
|
290
296
|
? buildSupervisor({
|
|
@@ -538,16 +544,21 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
|
|
|
538
544
|
const dispatch = async (req: Request): Promise<RpcResponse> => {
|
|
539
545
|
switch (req.kind) {
|
|
540
546
|
case 'register':
|
|
547
|
+
await awaitRestored()
|
|
541
548
|
return handleRegister(req)
|
|
542
549
|
case 'deregister':
|
|
550
|
+
await awaitRestored()
|
|
543
551
|
return handleDeregister(req)
|
|
544
552
|
case 'list':
|
|
545
553
|
return handleList()
|
|
546
554
|
case 'status':
|
|
555
|
+
await awaitRestored()
|
|
547
556
|
return handleStatus(req)
|
|
548
557
|
case 'restart':
|
|
558
|
+
await awaitRestored()
|
|
549
559
|
return handleRestart(req)
|
|
550
560
|
case 'secrets-patch':
|
|
561
|
+
await awaitRestored()
|
|
551
562
|
return handleSecretsPatch(req)
|
|
552
563
|
case 'http-info':
|
|
553
564
|
return handleHttpInfo()
|
|
@@ -614,12 +625,52 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
|
|
|
614
625
|
if (rpc.kind !== 'restart' && rpc.kind !== 'secrets-patch') {
|
|
615
626
|
return json({ ok: false, reason: 'http transport only supports restart and secrets-patch' }, 403)
|
|
616
627
|
}
|
|
628
|
+
// restartTokens is populated by boot-time restore; authorizing before it
|
|
629
|
+
// completes would reject a valid token as "invalid restart token".
|
|
630
|
+
await awaitRestored()
|
|
617
631
|
if (restartTokens.get(rpc.containerName) !== token) {
|
|
618
632
|
return json({ ok: false, reason: 'invalid restart token' }, 403)
|
|
619
633
|
}
|
|
620
634
|
return json(rpc.kind === 'restart' ? await handleRestart(rpc) : await handleSecretsPatch(rpc))
|
|
621
635
|
}
|
|
622
636
|
|
|
637
|
+
// GC tick distinguishes "container confirmed gone" from "docker call failed":
|
|
638
|
+
// a `docker ps` blip should not deregister a live container registration, so
|
|
639
|
+
// we require gcMissesToDeregister consecutive confirmed absences. Boot-time
|
|
640
|
+
// restore reuses the same probe but with a stricter policy — see
|
|
641
|
+
// restorePersistedRegistrations.
|
|
642
|
+
const probeContainerAlive = async (name: string): Promise<'alive' | 'gone' | 'unknown'> => {
|
|
643
|
+
try {
|
|
644
|
+
const result = await exec(['ps', '-a', '--filter', `name=^${name}$`, '--format', '{{.Names}}'])
|
|
645
|
+
if (result.exitCode !== 0) return 'unknown'
|
|
646
|
+
const names = result.stdout
|
|
647
|
+
.trim()
|
|
648
|
+
.split('\n')
|
|
649
|
+
.filter((s) => s.length > 0)
|
|
650
|
+
return names.includes(name) ? 'alive' : 'gone'
|
|
651
|
+
} catch {
|
|
652
|
+
return 'unknown'
|
|
653
|
+
}
|
|
654
|
+
}
|
|
655
|
+
|
|
656
|
+
// Boot-time restore replays every persisted registration into the in-memory
|
|
657
|
+
// maps and revives portbroker. It runs N docker-ps probes, so on a cold
|
|
658
|
+
// daemon it can take seconds — longer than the CLI's spawn-readiness window.
|
|
659
|
+
// We therefore start it WITHOUT blocking the listeners: the sockets accept
|
|
660
|
+
// connections immediately (so `isDaemonReachable` succeeds fast and the CLI
|
|
661
|
+
// injects the hostd env vars), but every handler that reads or mutates the
|
|
662
|
+
// restored registry awaits `awaitRestored` first. That preserves the original
|
|
663
|
+
// invariant — no RPC observes a half-restored registry — without coupling
|
|
664
|
+
// readiness to docker latency. Kicked off BEFORE the HTTP/IPC listeners so no
|
|
665
|
+
// request can slip past the gate in an unrestored window. A bad file (parse
|
|
666
|
+
// error, schema mismatch) is logged-and-skipped; one corrupt registration
|
|
667
|
+
// must not gate recovery.
|
|
668
|
+
restoreComplete = restorePersistedRegistrations(applyRegistration, log, probeContainerAlive, removeRegistrationFile)
|
|
669
|
+
// Swallow the rejection on a detached handle so a restore failure never
|
|
670
|
+
// becomes an unhandledRejection before the first gated handler awaits it.
|
|
671
|
+
// Handlers await `restoreComplete` directly so they still fail closed.
|
|
672
|
+
restoreComplete.catch(() => {})
|
|
673
|
+
|
|
623
674
|
const httpHostname = opts.httpHost ?? '0.0.0.0'
|
|
624
675
|
// Try the stable port first so containers' cached TYPECLAW_HOSTD_URL stays
|
|
625
676
|
// valid across hostd respawns. EADDRINUSE means another local service holds
|
|
@@ -649,32 +700,6 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
|
|
|
649
700
|
httpPort = httpServer.port ?? 0
|
|
650
701
|
log({ kind: 'daemon-http-listening', host: httpHostname, port: httpPort })
|
|
651
702
|
|
|
652
|
-
// GC tick distinguishes "container confirmed gone" from "docker call failed":
|
|
653
|
-
// a `docker ps` blip should not deregister a live container registration, so
|
|
654
|
-
// we require gcMissesToDeregister consecutive confirmed absences. Boot-time
|
|
655
|
-
// restore reuses the same probe but with a stricter policy — see
|
|
656
|
-
// restorePersistedRegistrations.
|
|
657
|
-
const probeContainerAlive = async (name: string): Promise<'alive' | 'gone' | 'unknown'> => {
|
|
658
|
-
try {
|
|
659
|
-
const result = await exec(['ps', '-a', '--filter', `name=^${name}$`, '--format', '{{.Names}}'])
|
|
660
|
-
if (result.exitCode !== 0) return 'unknown'
|
|
661
|
-
const names = result.stdout
|
|
662
|
-
.trim()
|
|
663
|
-
.split('\n')
|
|
664
|
-
.filter((s) => s.length > 0)
|
|
665
|
-
return names.includes(name) ? 'alive' : 'gone'
|
|
666
|
-
} catch {
|
|
667
|
-
return 'unknown'
|
|
668
|
-
}
|
|
669
|
-
}
|
|
670
|
-
|
|
671
|
-
// Boot-time restore: replay every persisted registration into the in-memory
|
|
672
|
-
// maps and revive portbroker for it. Runs before the IPC listener so the socket
|
|
673
|
-
// is never accepting RPCs against a half-restored registry. A bad file
|
|
674
|
-
// (parse error, schema mismatch) is logged-and-skipped — one corrupt
|
|
675
|
-
// registration must not gate every other container's recovery.
|
|
676
|
-
await restorePersistedRegistrations(applyRegistration, log, probeContainerAlive, removeRegistrationFile)
|
|
677
|
-
|
|
678
703
|
const sockets = new Set<NetSocket>()
|
|
679
704
|
const listener = createServer((socket) => {
|
|
680
705
|
const state = { buf: '' }
|
|
@@ -734,6 +759,10 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
|
|
|
734
759
|
clearInterval(gcTimer)
|
|
735
760
|
await closeSocketServer(listener, sockets)
|
|
736
761
|
httpServer.stop(true)
|
|
762
|
+
// A stop racing an in-flight boot restore could let a portbroker start
|
|
763
|
+
// after the teardown loop below already ran, leaking it. Let restore
|
|
764
|
+
// settle (it never rejects past the detached catch) before tearing down.
|
|
765
|
+
await (restoreComplete ?? Promise.resolve()).catch(() => {})
|
|
737
766
|
if (opts.portbroker) {
|
|
738
767
|
const names = Array.from(cwds.keys())
|
|
739
768
|
await Promise.allSettled(names.map((n) => opts.portbroker!.stop(n, 'broker-stopped')))
|
package/src/hostd/spawn.ts
CHANGED
|
@@ -111,12 +111,48 @@ async function ensureDaemonWithRetry(opts: EnsureDaemonOptions, retriesLeft: num
|
|
|
111
111
|
if (httpPort === null) return { ok: false, reason: 'daemon did not report an HTTP control port' }
|
|
112
112
|
return { ok: true, pid: await readPidQuiet(), spawned: false, httpPort }
|
|
113
113
|
}
|
|
114
|
+
// A prior spawn attempt can leave a live-but-not-yet-listening child (its
|
|
115
|
+
// readiness poll timed out without killing it — see spawnDaemonDetached).
|
|
116
|
+
// Spawning a second daemon would race two processes for the same socket, so
|
|
117
|
+
// adopt the existing child and poll IT for readiness instead of re-spawning.
|
|
118
|
+
const existingPid = await livePidfileChild()
|
|
119
|
+
if (existingPid !== null) {
|
|
120
|
+
const ready = await pollForReadiness(opts.spawnTimeoutMs ?? DEFAULT_SPAWN_TIMEOUT_MS)
|
|
121
|
+
if (ready === null) return { ok: false, reason: 'daemon spawned but did not become reachable yet' }
|
|
122
|
+
return { ok: true, pid: existingPid, spawned: false, httpPort: ready }
|
|
123
|
+
}
|
|
114
124
|
return await spawnDaemonDetached(opts)
|
|
115
125
|
} finally {
|
|
116
126
|
await releaseLock(lock.token)
|
|
117
127
|
}
|
|
118
128
|
}
|
|
119
129
|
|
|
130
|
+
// Reads the pidfile and returns its pid only if that process is still alive
|
|
131
|
+
// (signal 0 = existence check, no signal delivered). Returns null when the
|
|
132
|
+
// pidfile is absent/garbage or the process has exited — i.e. nothing to adopt.
|
|
133
|
+
async function livePidfileChild(): Promise<number | null> {
|
|
134
|
+
const pid = await readPidQuiet()
|
|
135
|
+
if (pid <= 0) return null
|
|
136
|
+
try {
|
|
137
|
+
process.kill(pid, 0)
|
|
138
|
+
return pid
|
|
139
|
+
} catch {
|
|
140
|
+
return null
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
async function pollForReadiness(timeoutMs: number): Promise<number | null> {
|
|
145
|
+
const deadline = Date.now() + timeoutMs
|
|
146
|
+
while (Date.now() < deadline) {
|
|
147
|
+
if (await isDaemonReachable()) {
|
|
148
|
+
const httpPort = await readHttpPort()
|
|
149
|
+
if (httpPort !== null) return httpPort
|
|
150
|
+
}
|
|
151
|
+
await sleep(POLL_INTERVAL_MS)
|
|
152
|
+
}
|
|
153
|
+
return null
|
|
154
|
+
}
|
|
155
|
+
|
|
120
156
|
async function spawnDaemonDetached(opts: EnsureDaemonOptions): Promise<SpawnAttemptResult> {
|
|
121
157
|
// Bun.spawn() with `stdout: <number>` consumes the file descriptor by
|
|
122
158
|
// dup()-ing it into the child; the parent's handle remains valid until we
|
|
@@ -154,26 +190,24 @@ async function spawnDaemonDetached(opts: EnsureDaemonOptions): Promise<SpawnAtte
|
|
|
154
190
|
return { ok: false, reason: `failed to write daemon pidfile: ${stringify(error)}` }
|
|
155
191
|
}
|
|
156
192
|
|
|
157
|
-
const
|
|
158
|
-
|
|
159
|
-
if (await isDaemonReachable()) {
|
|
160
|
-
const httpPort = await readHttpPort()
|
|
161
|
-
if (httpPort !== null) return { ok: true, pid: proc.pid, spawned: true, httpPort }
|
|
162
|
-
}
|
|
163
|
-
await sleep(POLL_INTERVAL_MS)
|
|
164
|
-
}
|
|
193
|
+
const httpPort = await pollForReadiness(opts.spawnTimeoutMs ?? DEFAULT_SPAWN_TIMEOUT_MS)
|
|
194
|
+
if (httpPort !== null) return { ok: true, pid: proc.pid, spawned: true, httpPort }
|
|
165
195
|
|
|
166
|
-
//
|
|
167
|
-
//
|
|
168
|
-
//
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
196
|
+
// Timed out waiting for readiness. A still-running child is "slow-booting",
|
|
197
|
+
// not "wedged" — killing it would throw away a daemon that's about to come up
|
|
198
|
+
// and force every caller into a respawn loop. Only reap a child that already
|
|
199
|
+
// EXITED (proc.exitCode !== null): that's a genuine failure with a dangling
|
|
200
|
+
// pidfile to clean. A live-but-not-ready child is left running so the caller
|
|
201
|
+
// can re-probe it (see registerWithDaemon's retry) — the next ensureDaemon()
|
|
202
|
+
// fast-paths through isDaemonReachable() once its socket binds.
|
|
203
|
+
if (proc.exitCode !== null) {
|
|
204
|
+
try {
|
|
205
|
+
const raw = await readFile(pidfilePath(), 'utf8').catch(() => '')
|
|
206
|
+
if (raw.trim() === String(proc.pid)) await unlink(pidfilePath())
|
|
207
|
+
} catch {}
|
|
208
|
+
return { ok: false, reason: 'daemon exited before becoming reachable' }
|
|
209
|
+
}
|
|
210
|
+
return { ok: false, reason: 'daemon spawned but did not become reachable yet' }
|
|
177
211
|
}
|
|
178
212
|
|
|
179
213
|
type LockToken = { path: string }
|
|
@@ -15,6 +15,14 @@ export type PermissionService = {
|
|
|
15
15
|
// either side and MUST be treated as deny, never allow — mistreating it
|
|
16
16
|
// as allow reopens the privilege-escalation hole this gate closes.
|
|
17
17
|
compareRoleSeverity(a: string, b: string): -1 | 0 | 1 | undefined
|
|
18
|
+
// Resolved (wildcard-expanded) permission set for a role NAME, or
|
|
19
|
+
// `undefined` for an unknown role. Unlike `describe`, which takes an
|
|
20
|
+
// origin, this answers "what can role X do" directly — needed for
|
|
21
|
+
// capability-dominance checks (e.g. "may the caller schedule deferred
|
|
22
|
+
// work as role X") that cannot use the coarse `compareRoleSeverity`
|
|
23
|
+
// tower, since custom roles are arbitrary permission bags with no
|
|
24
|
+
// inherent ordering. Callers MUST treat `undefined` as deny.
|
|
25
|
+
permissionsForRole(role: string): readonly string[] | undefined
|
|
18
26
|
// Rebuilds the resolved role table from the given roles config, preserving
|
|
19
27
|
// the same plugin-permission set captured at construction time. Used by
|
|
20
28
|
// the config reloadable so role match-rule edits (typeclaw role claim,
|
|
@@ -43,6 +51,7 @@ export const noopPermissionService: PermissionService = {
|
|
|
43
51
|
has: () => false,
|
|
44
52
|
resolveRole: () => 'guest',
|
|
45
53
|
compareRoleSeverity: () => undefined,
|
|
54
|
+
permissionsForRole: () => undefined,
|
|
46
55
|
describe: () => ({ role: 'guest', permissions: [] }),
|
|
47
56
|
replaceRoles: () => {},
|
|
48
57
|
replacePluginPermissions: () => {},
|
|
@@ -193,6 +202,9 @@ export function createPermissionService(opts: CreatePermissionServiceOptions = {
|
|
|
193
202
|
if (aRank > bRank) return 1
|
|
194
203
|
return 0
|
|
195
204
|
},
|
|
205
|
+
permissionsForRole(role) {
|
|
206
|
+
return byName.get(role)?.permissions
|
|
207
|
+
},
|
|
196
208
|
describe(origin) {
|
|
197
209
|
const name = resolveRole(origin)
|
|
198
210
|
const role = byName.get(name)
|
|
@@ -42,11 +42,16 @@ export type CodexFetchObserverOptions = {
|
|
|
42
42
|
// request occupied 901s before Bun's OS socket deadline fired). On expiry the
|
|
43
43
|
// request is aborted with a retryable error, so this also bounds how long a
|
|
44
44
|
// user waits before the retry fires — keeping it low is a UX requirement, not
|
|
45
|
-
// just a safety net. Default
|
|
46
|
-
//
|
|
47
|
-
//
|
|
48
|
-
//
|
|
49
|
-
//
|
|
45
|
+
// just a safety net. Default 300_000 ms (raised from 120_000): the 120s cap
|
|
46
|
+
// was tuned against a light-turn sample (slowest healthy ~45s, p99 ~30s) and
|
|
47
|
+
// aborted heavy reasoning turns that were still legitimately trickling bytes
|
|
48
|
+
// — PR reviews, the `dreaming` memory consolidation, and long channel threads
|
|
49
|
+
// routinely run a slow-trickle stream past 2min (observed total_ms=120009 with
|
|
50
|
+
// body_bytes>700k on otherwise-progressing turns). Those are NOT the silent
|
|
51
|
+
// hang this timer exists to catch; the sliding `idleMs` (still 120s) already
|
|
52
|
+
// bounds genuine dead air per-chunk, so the wall-clock ceiling only needs to
|
|
53
|
+
// stop a never-terminating stream. 300s caps a real hang at ~5min while giving
|
|
54
|
+
// heavy turns the headroom they need. Set to 0 to disable just this timer.
|
|
50
55
|
overallMs?: number
|
|
51
56
|
// Schedule fn for tests. Receives (delayMs, callback) and returns a handle
|
|
52
57
|
// the wrapper can pass to `clear`. Default: `setTimeout`/`clearTimeout`.
|
|
@@ -67,7 +72,7 @@ const ENV_IDLE_MS = 'TYPECLAW_CODEX_IDLE_MS'
|
|
|
67
72
|
const ENV_OVERALL_MS = 'TYPECLAW_CODEX_OVERALL_MS'
|
|
68
73
|
const DEFAULT_TTFB_MS = 15_000
|
|
69
74
|
const DEFAULT_IDLE_MS = 120_000
|
|
70
|
-
const DEFAULT_OVERALL_MS =
|
|
75
|
+
const DEFAULT_OVERALL_MS = 300_000
|
|
71
76
|
const LOG_PREFIX = '[codex-fetch]'
|
|
72
77
|
|
|
73
78
|
const defaultScheduler: TimeoutScheduler = {
|
package/src/secrets/oauth-xai.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { createServer, type Server } from 'node:http'
|
|
2
2
|
|
|
3
|
-
import { registerOAuthProvider } from '@mariozechner/pi-ai/oauth'
|
|
3
|
+
import { getOAuthProvider, registerOAuthProvider } from '@mariozechner/pi-ai/oauth'
|
|
4
4
|
import type { OAuthCredentials, OAuthLoginCallbacks, OAuthProviderInterface } from '@mariozechner/pi-ai/oauth'
|
|
5
5
|
|
|
6
6
|
// xAI (Grok) OAuth 2.0. xAI runs a standard OIDC authorization server at
|
|
@@ -336,7 +336,7 @@ let registered = false
|
|
|
336
336
|
// so the provider is always present before `AuthStorage.login()` /
|
|
337
337
|
// `getApiKey()` look it up via `getOAuthProvider('xai')`.
|
|
338
338
|
export function registerXaiOAuthProvider(): void {
|
|
339
|
-
if (registered) return
|
|
339
|
+
if (registered && getOAuthProvider(XAI_OAUTH_PROVIDER_ID)) return
|
|
340
340
|
registerOAuthProvider(xaiOAuthProvider)
|
|
341
341
|
registered = true
|
|
342
342
|
}
|
package/src/server/index.ts
CHANGED
|
@@ -12,8 +12,10 @@ import { applyTurnThinkingLevel, getQuestionSignal, type QuestionSignal } from '
|
|
|
12
12
|
import { runPluginDoctorChecks, runPluginDoctorFix } from '@/agent/doctor'
|
|
13
13
|
import type { LiveSessionRegistry } from '@/agent/live-sessions'
|
|
14
14
|
import type { LiveSubagentRegistry } from '@/agent/live-subagents'
|
|
15
|
+
import { resolveFallbackChain } from '@/agent/model-fallback'
|
|
16
|
+
import { applyModelRuntimeOverrides } from '@/agent/model-overrides'
|
|
15
17
|
import { forgetSharedLoopGuardTool } from '@/agent/plugin-tools'
|
|
16
|
-
import { detectProviderError } from '@/agent/provider-error'
|
|
18
|
+
import { detectProviderError, isThrottleOrOverload } from '@/agent/provider-error'
|
|
17
19
|
import { requestContainerRestart } from '@/agent/restart'
|
|
18
20
|
import { consumeRestartHandoff, type RestartHandoff } from '@/agent/restart-handoff'
|
|
19
21
|
import { sessionMetaPayload } from '@/agent/session-meta'
|
|
@@ -29,7 +31,9 @@ import {
|
|
|
29
31
|
runIdleContinuation,
|
|
30
32
|
} from '@/agent/todo/continuation-wiring'
|
|
31
33
|
import { SUBAGENT_OUTPUT_TOOL_NAME } from '@/agent/tools/subagent-output'
|
|
34
|
+
import { promptPersistentTurnWithFallback } from '@/agent/turn-runner'
|
|
32
35
|
import type { ChannelRouter } from '@/channels/router'
|
|
36
|
+
import { getConfig, resolveModel } from '@/config'
|
|
33
37
|
import { aggregateCronList, type CronJob, type CronListEntry, loadCron } from '@/cron'
|
|
34
38
|
import type { McpManager } from '@/mcp'
|
|
35
39
|
import type { HookBus } from '@/plugin'
|
|
@@ -183,6 +187,7 @@ type QueuedPrompt = {
|
|
|
183
187
|
|
|
184
188
|
type SessionState = {
|
|
185
189
|
session: AgentSession
|
|
190
|
+
activeModelRef: ReturnType<typeof resolveFallbackChain>[number]
|
|
186
191
|
// The session's creation-time thinking level, captured once. An escalated turn
|
|
187
192
|
// moves `session.thinkingLevel` to `high`, so neither turn-driving path (drain
|
|
188
193
|
// loop, no-stream fallback) can use the live getter as the reset target — both
|
|
@@ -535,6 +540,7 @@ export function createServer({
|
|
|
535
540
|
|
|
536
541
|
const state: SessionState = {
|
|
537
542
|
session,
|
|
543
|
+
activeModelRef: resolveFallbackChain(getConfig().models, undefined)[0]!,
|
|
538
544
|
turnThinkingDefault: session.thinkingLevel,
|
|
539
545
|
lastQuestionSignal: null,
|
|
540
546
|
sessionFileId,
|
|
@@ -1111,7 +1117,26 @@ async function drain(
|
|
|
1111
1117
|
? `${renderTurnTimeAnchor()}\n\n${item.text}\n\n${retrievalContext.results}`
|
|
1112
1118
|
: `${renderTurnTimeAnchor()}\n\n${item.text}`
|
|
1113
1119
|
applyTurnThinkingLevel(state.session, item.text, state.turnThinkingDefault, state.lastQuestionSignal)
|
|
1114
|
-
await
|
|
1120
|
+
const result = await promptPersistentTurnWithFallback({
|
|
1121
|
+
refs: resolveFallbackChain(getConfig().models, undefined),
|
|
1122
|
+
currentModelRef: state.activeModelRef,
|
|
1123
|
+
session: state.session,
|
|
1124
|
+
text: turnText,
|
|
1125
|
+
shouldFailover: (err) => isThrottleOrOverload(err.message),
|
|
1126
|
+
setModelForRef: async (ref) => {
|
|
1127
|
+
await state.session.setModel(applyModelRuntimeOverrides(resolveModel(ref), ref))
|
|
1128
|
+
state.activeModelRef = ref
|
|
1129
|
+
},
|
|
1130
|
+
beforeAttempt: () => {
|
|
1131
|
+
applyTurnThinkingLevel(state.session, item.text, state.turnThinkingDefault, state.lastQuestionSignal)
|
|
1132
|
+
},
|
|
1133
|
+
onAttemptFailed: (attempt) => {
|
|
1134
|
+
logger.warn(
|
|
1135
|
+
`[server] ${state.sessionFileId}: ${attempt.outcome} failure on ${attempt.ref}: ${attempt.errorMessage ?? 'unknown'}; falling back`,
|
|
1136
|
+
)
|
|
1137
|
+
},
|
|
1138
|
+
})
|
|
1139
|
+
if (result.success) state.activeModelRef = result.refUsed
|
|
1115
1140
|
// Only real user turns move the signal: a usable turn seeds it, a failed
|
|
1116
1141
|
// leaf CLEARS it (else an older question leaks across the failed turn).
|
|
1117
1142
|
// Todo-continuation turns are not user turns, so they leave it untouched.
|
|
@@ -79,7 +79,7 @@ This says: the `discord-bot` adapter is enabled with default engagement; one spe
|
|
|
79
79
|
This is a **`roles`** edit, not a `channels` edit. See the `typeclaw-permissions` skill for the full procedure. Short version:
|
|
80
80
|
|
|
81
81
|
1. Get the platform ID (Discord channel ID, Slack channel ID, Telegram chat ID, LINE chat ID, KakaoTalk chat ID).
|
|
82
|
-
2. Append a match-rule to `roles.member.match` using the canonical DSL (`discord:<guild>/<channel>`, `slack:<team>/<channel>`, `telegram:<chat>`, for LINE the bucketed form `line:dm/<chatId>`, `line:group/<chatId>`, or `line:square/<chatId>` — pick the bucket from the chat's classification; an unbucketed `line:<chatId>` is read as a workspace and never matches — and `kakao:<chat>`).
|
|
82
|
+
2. Append a match-rule to `roles.member.match` using the canonical DSL (`discord:<guild>/<channel>`, `slack:<team>/<channel>`, `telegram:<chat>`, for LINE the bucketed form `line:dm/<chatId>`, `line:group/<chatId>`, or `line:square/<chatId>` — pick the bucket from the chat's classification; an unbucketed `line:<chatId>` is read as a workspace and never matches — and `kakao:<chat>`). The `rolePromotion` security guard blocks any widening of `roles.<role>.match` and no longer accepts `acknowledgeGuards` — the ack flag is ignored for this guard. The write must come from a session that already holds `security.bypass.medium` (the TUI is always `owner`; a role granted `security.bypass.medium` also qualifies), or the user must claim the role out-of-band via `typeclaw role claim` from the host CLI. See `typeclaw-permissions` for the full procedure and the strong warning never to widen roles on behalf of a channel speaker asking to elevate themselves.
|
|
83
83
|
3. **`roles.<role>.match[]` edits are live-reloadable** — they take effect on the next `typeclaw reload` (the classifier marks `roles.match` as `applied`, and the permission service rebuilds its role table). Only `roles.<role>.permissions[]` edits are restart-required. So adding a match-rule to admit a channel applies on `reload`; no container restart needed.
|
|
84
84
|
|
|
85
85
|
### When the user asks "stop replying in this channel"
|
|
@@ -15,6 +15,7 @@ The runtime reads `typeclaw.json` at container startup. Some fields are picked u
|
|
|
15
15
|
|
|
16
16
|
- `port` — the TCP port the websocket server binds to inside the container. The TUI on the host stage connects to this. Default `8973`. **Restart-required.**
|
|
17
17
|
- `model` — a fully-qualified `<provider>/<model-id>` string. The runtime resolves this against the built-in provider registry to decide which API to call for every turn. **Live-reloadable.**
|
|
18
|
+
- `models.<profile>` fallback chain — a profile may be an array of refs. The chain advances on failure: cron/batch turns advance on **any** error; interactive turns (TUI, channels, subagents) advance only when the active ref is **throttled/overloaded** (`server_is_overloaded`/`429`/`503`/rate-limit), never mid-turn after output or a tool call, and a repeatedly-throttled ref is skipped for a short cooldown. A single-ref profile fails fast with a provider notice instead of stalling. To make an agent resilient to per-account provider throttling, declare a fallback ref (ideally a different provider/account). **Live-reloadable** (rides `models`).
|
|
18
19
|
- `thinkingLevel` (per-profile) — reasoning effort lives **inside `models`**, not as a top-level field. A profile value may be an object like `{ "model": "<ref>", "thinkingLevel": "high" }` (or `{ "models": ["<ref>", …], "thinkingLevel": … }` for a chain). A session resolves its effort as **the profile's own level → the `default` profile's level → the SDK default (`medium`)** — so the `default` profile's `thinkingLevel` is the de-facto global default, mirroring how `models.default` is the default model. Levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. Clamped to each model's capabilities (`xhigh` is OpenAI-family-only). An attention-escalation cue in a turn still bumps that single turn to maximum effort regardless. Bare string/array profile values keep working; a profile becomes an object only when a level is attached. **Live-reloadable** (rides `models`).
|
|
19
20
|
- `mounts` — additional host directories the user has chosen to expose to you. Each entry produces a `docker run -v <hostPath>:/agent/mounts/<name>` flag at `typeclaw start` time, so the directory shows up at `mounts/<name>` inside your agent folder. **The launcher reads this; the running container does not.** Editing `mounts` only takes effect on the next `typeclaw start`. **Restart-required.**
|
|
20
21
|
- `plugins` — array of plugin module specifiers loaded at server boot: npm package names for published plugins, or relative paths for local plugins you are authoring. **Restart-required.**
|
|
@@ -115,7 +115,7 @@ But to keep `cron.json` clean, **a one-shot `prompt` job should remove its own e
|
|
|
115
115
|
|
|
116
116
|
> "... After delivering the reminder, remove the cron job with id `cancel-sub` from `cron.json` and call the `reload` tool so the dead one-shot doesn't linger."
|
|
117
117
|
|
|
118
|
-
Removing a job
|
|
118
|
+
Removing a job passes the `cronPromotion` guard freely — deletions are privilege reductions and are never blocked. If the cleanup is ever skipped (model error, crash mid-session), the worst case is a harmless leftover entry you can prune on any later edit — never a broken schedule. This self-prune only applies to `prompt` jobs; an `at` `exec` job has no LLM to clean up after itself, so its entry just lingers until a human or a later prompt removes it.
|
|
119
119
|
|
|
120
120
|
## `exec → LLM`: write a plugin cron handler (best practice)
|
|
121
121
|
|
|
@@ -360,7 +360,12 @@ If you set `timezone`, the schedule is interpreted in that zone. **Always set `t
|
|
|
360
360
|
|
|
361
361
|
1. **Read the whole file first** with the `read` tool. Don't assume what's in it.
|
|
362
362
|
2. **Modify in memory.** Add, remove, or change jobs in the parsed JSON.
|
|
363
|
-
3. **Write the whole file back** with the `write` tool. Always pretty-printed (2-space indent), trailing newline, sorted-stable order.
|
|
363
|
+
3. **Write the whole file back** with the `write` tool. Always pretty-printed (2-space indent), trailing newline, sorted-stable order. The `cronPromotion` security guard is **caller-role-aware** and no longer accepts `acknowledgeGuards` — the ack flag is ignored for this guard. Instead, the guard checks whether the change schedules deferred work above your current resolved role:
|
|
364
|
+
- **Passes automatically (no ack needed or possible):** adding a new job whose `scheduledByRole` is at or below your role; editing the body (`kind`, `prompt`, `command`, `subagent`, `payload`) of a job whose `scheduledByRole` is at or below your role; changing `scheduledByRole` to a value at or below your role; re-enabling a job whose `scheduledByRole` is at or below your role; removing a job; disabling a job (`enabled: true → false`); cadence-only changes (`schedule`/`timezone`).
|
|
365
|
+
- **Blocked:** adding a job with `scheduledByRole` above your role; changing `scheduledByRole` to a value above your role; editing the body of a job whose `scheduledByRole` is already above your role; re-enabling a job whose `scheduledByRole` is above your role. These are the deferred-laundering attacks the guard exists to catch.
|
|
366
|
+
|
|
367
|
+
The role tower is `owner > trusted > member > guest`. A `member` session can freely add or edit jobs stamped `scheduledByRole: "member"` or `"guest"`, but cannot touch jobs stamped `"owner"` or `"trusted"`. When blocked, the resolution is NOT an ack — make the change from a session that already resolves to a sufficiently high role (the TUI is always `owner`; a role granted `security.bypass.medium` also bypasses), or claim the role out-of-band via `typeclaw role claim` from the host CLI. **Never attempt to schedule a job that fires as a role higher than the requesting channel speaker** — that is exactly the deferred-privilege-escalation attack the guard blocks.
|
|
368
|
+
|
|
364
369
|
4. **Apply with the `reload` tool.** Call the `reload` tool — it re-reads `cron.json` and updates the live scheduler. The tool returns `[cron] ok: ...` with an added/removed/updated/unchanged summary on success, or `[cron] failed: ...` with the exact validation error on failure. **If reload fails, the live schedule is left unchanged** — fix `cron.json` based on the error message and call `reload` again.
|
|
365
370
|
5. **Commit the change** _after_ a successful reload. See the `typeclaw-git` skill for the commit-message rule (decision context required). `cron.json` is not gitignored, so an uncommitted edit will pollute your next commit.
|
|
366
371
|
|
|
@@ -369,7 +374,7 @@ If you set `timezone`, the schedule is interpreted in that zone. **Always set `t
|
|
|
369
374
|
If a user tells you to **stop / turn off / disable** something you keep doing — most often a message you post to a channel on a repeating cadence ("turn that off", "stop sending this", "왜 자꾸 보내", "make it stop") — that repeating side effect is almost always one of your own cron jobs firing a `prompt`. The channel message that annoys them carries **no marker** tying it back to a job, so you have to find it yourself. Do this:
|
|
370
375
|
|
|
371
376
|
1. **Read `cron.json`** (or run `typeclaw cron list` for the live view incl. plugin jobs). Find the job whose `prompt`/`command` produces the thing the user is complaining about — match on the content of the repeated message, the cadence they mention ("every 30 minutes"), or the channel it lands in.
|
|
372
|
-
2. **Disable or remove it.** Set `"enabled": false` to keep the entry but stop it firing (reversible), or delete the job entry entirely if they want it gone.
|
|
377
|
+
2. **Disable or remove it.** Set `"enabled": false` to keep the entry but stop it firing (reversible), or delete the job entry entirely if they want it gone. Both pass the `cronPromotion` guard automatically — disabling and removing are privilege reductions, never the deferred-grant the guard blocks. Do **not** edit the job's `prompt`/`command` body just to neutralize it; that is a body change that may be blocked if the job fires above your current role, and it's the wrong tool anyway.
|
|
373
378
|
3. **Call `reload`.** Until you do, the live scheduler keeps firing the old job no matter what you wrote to disk — saying "I turned it off" without a successful `reload` is the single most common way to fail this. Confirm the reload summary shows the job under `removed`/`updated` before you tell the user it's stopped.
|
|
374
379
|
4. **Commit** after the reload succeeds.
|
|
375
380
|
|
|
@@ -422,7 +427,7 @@ For a **recurring** job:
|
|
|
422
427
|
2. **Translate the cadence to cron.** "Every morning at 7" → `0 7 * * *`. "Every weekday at 9:30" → `30 9 * * 1-5`. "Every five minutes" → `*/5 * * * *`. If you are not sure, ask once. Don't guess on tricky cases like "every other Friday". If the user wants the recurrence to stop ("until end of quarter", "only 5 times"), add `until` (absolute ISO instant) and/or `count` (N fires).
|
|
423
428
|
3. **Timezone.** If the user mentioned a wall-clock time, set `timezone` to their zone. If unknown, ask once or default to the timezone in `USER.md` if it's recorded there.
|
|
424
429
|
4. **Pick a stable `id`.** Use kebab-case that describes the job, not the schedule. `daily-summary` not `0-23-30`.
|
|
425
|
-
5. **Write it. Call `reload`. If reload succeeded, commit it.** If reload failed, fix `cron.json` based on the error and retry — do not commit a broken file.
|
|
430
|
+
5. **Write it. Call `reload`. If reload succeeded, commit it.** If reload failed, fix `cron.json` based on the error and retry — do not commit a broken file. Adding a new job whose `scheduledByRole` is at or below your current role passes the `cronPromotion` guard automatically — no ack is needed or accepted. If the job's `scheduledByRole` is above your current role, the guard blocks the write; make the change from a higher-role session (TUI is always `owner`) or via `typeclaw role claim` from the host CLI. See step 3 of "Editing `cron.json` safely" for the full caller-role-aware model.
|
|
426
431
|
|
|
427
432
|
## Listing what is currently scheduled
|
|
428
433
|
|