Horae JSON Schemas¶
Machine-readable contracts for the documents Horae reads and writes (PLAN.md §3).
All schemas use JSON Schema draft 2020-12. $id values below are relative to
https://raw.githubusercontent.com/horae-dev/horae/main/schemas/.
| Schema | File | $id (relative) |
Validates |
|---|---|---|---|
| Pipeline | pipeline/v1.json |
pipeline/v1.json |
pipelines/*.yaml (§3.2) |
| Plugin manifest | plugin-manifest/v1.json |
plugin-manifest/v1.json |
plugin.yaml (§3.3) |
| Intent (any) | intent/v1.json |
intent/v1.json |
one intent, oneOf tagged by a type const |
| One intent | intents/<type>/v1.json |
intents/<type>/v1.json |
note.create, note.append_section, note.replace_owned_block, task.create, task.update_status, notify.push, http.post |
| Lockfile | lockfile/v1.json |
lockfile/v1.json |
horae.lock (§4) |
| Marketplace index | marketplace/v1.json |
marketplace/v1.json |
marketplace.json of a marketplace repository (§4) |
| Run record | run-record/v1.json |
run-record/v1.json |
one run (§3.1, §2.1.6) |
| Instance configuration | instance/v1.json |
instance/v1.json |
horae.yaml (§3.1, §3.4, §7) |
| Skill | skill/v1.json |
skill/v1.json |
skills/<namespace>/<skill>/skill.yaml of a plugin (§2.1, §3.4) |
| Eval case | eval-case/v1.json |
eval-case/v1.json |
skills/<namespace>/<skill>/evals/<case>.yaml (§5) |
| Eval recorded response | eval-recorded/v1.json |
eval-recorded/v1.json |
evals/recorded/<backend>/<case>.json (§5) |
Source of truth¶
The pydantic models in src/horae/contracts/ are the source of truth
(public types such as Hostname, NotePath or SecretName live in horae.contracts.types and
are re-exported from horae.contracts). The files here are generated; do not edit them by hand:
uv run python -m horae.contracts.export # regenerate schemas/ (from any directory)
uv run python -m horae.contracts.export --check # exit 1 if schemas/ is stale
tests/test_contracts.py fails if the committed files differ from what the models generate
(byte for byte, LF line endings: see .gitattributes), if a *.json file outside examples/ is
not a generated schema, and checks that the schemas and the models agree on every example.
The output bytes depend on the pydantic version locked in uv.lock. A Renovate bump of
pydantic may change them; the drift test then fails in CI and the fix is to regenerate.
Versioning¶
- Each schema has a versioned
$id,https://raw.githubusercontent.com/horae-dev/horae/main/schemas/<name>/v<N>.json, and lives at<name>/v<N>.json, so the$idresolves to the file once it is onmain. - A breaking change adds
v<N+1>.jsonnext to the old file; compatible additions stay inv<N>. Most rules are deliberately tight: loosening one later is a compatible change. - Files that Horae writes itself carry
schema_version(horae.lock, run records). Files that people write (pipelines,plugin.yaml) do not, so the PLAN.md examples validate unchanged.horae.yamlaccepts an optionalschema_version: 1(the default), so that a future v2 file can be told apart (decision 26).
Rules worth knowing¶
- Unknown keys are rejected everywhere (
additionalProperties: false), except the free-form parameters of a plugin call and recorded data (source outputs, LLM requests and responses). - No type coercion. A string is never a number, a number never a string, and
trueis never an integer (not evenschema_version: 1). Dates are ISO 8601 strings:YYYY-MM-DD, or RFC 3339 date-times with seconds and an explicit offset (2026-10-27T05:30:00Z, upper-caseT/Z). Naive date-times are rejected. The models accept the same strings from JSON (validate_json) and from already-parsed data (validate_python, e.g.json.loads, MCP or SQLite rows), and alsodate/datetimeobjects from Python code. In YAML, quote dates: an unquoted2026-10-27is a YAML timestamp, not a string, and the JSON Schema rejects it. - A pipeline step is an object with exactly one key:
collect,transform,llm,actornotify. Each lists plugin calls, either bare (tasks.normalize) or with parameters (calendar.events: { days: 2 }), or in the explicit form with a per-call timeout ({ tool: calendar.events, params: { days: 2 }, timeout_s: 90 }, decision 35). A pipeline has at most onellmstep (contains+maxContains: 1). - The
llmstep has notoolskey, and requires a budget with bothusdandtokens_out. - Plugin permissions (
network,secrets,paths,intents) default to empty: no access. - Sinks apply intents (PLAN.md §3.1, §3.3);
permissions.intentslists the intents a plugin may propose or, for a sink, apply. - Sizes are bounded: lists and maps at most 256 entries; note content at most 1 MiB (1 048 576
characters, i.e. code points); titles 500, headings 200, notification bodies and messages 4096
characters; captured
stderr64 KiB; URLs 2048; paths 1024 (255 per segment).
Strings that reach the outside world¶
| Type | Rule |
|---|---|
Host (permissions.network) |
lowercase DNS name; the last label starts with a letter, so no IP literal (dotted, decimal, hex or IPv6); localhost and *.localhost rejected; single-label names (coach, a Docker/Coolify service) allowed; no port, scheme or wildcard |
http.post.url, runtime.url, homepage |
https:// only; host as above; optional port 1–65535; no user info, fragment, backslash, whitespace or control characters |
notify.push.link |
https:// or obsidian://, then [^\x00-\x20\x7f]+ |
task.create.link |
https://, a non-empty authority without @ (no user info), then optionally /, ? or # and the rest; no whitespace, control character or backslash anywhere; at most 2048 characters (decision 52) |
Lockfile repo |
https://<host>/<segments> with segments of A-Z a-z 0-9 . _ - (.git optional), no ./.. segment, no port, user info, query or fragment, at most 512 characters |
| Note path (intents) | relative POSIX path: no leading /, no \, no control characters, no empty segment, no segment starting with . (so no ., .., .obsidian/ or hidden files) |
permissions.paths |
normalised absolute POSIX path: no ./../empty segment, no trailing /, not /, no \ or control characters |
| Secret name | ^[A-Z][A-Z0-9_]*$ (not starting with _); HORAE_* reserved; LD_*, DYLD_*, PYTHON*, PATH, HOME rejected |
models.<alias>.base_url (horae.yaml) |
https:// to a host name (localhost included), an IPv4 literal or a bracketed IPv6 literal; http:// only to localhost, 127.0.0.0/8, 10/8, 172.16/12, 192.168/16, [::1], [fc00::/7] or a single-label name (ollama); optional port; no user info, fragment, backslash, whitespace or control characters (decision 24) |
| Task title, headings, descriptions | one line: ^[^\x00-\x1f\x7f]+$ |
| Block id | ^[a-z0-9][a-z0-9-]{0,63}$ |
Fingerprint (task.create.fingerprint, task.update_status.task) |
^[A-Za-z0-9._:-]{1,128}$ |
| Run id | ^[A-Za-z0-9._-]{1,128}$ (safe as a file name) |
Contracts constrain shape, not meaning. The runtime still has to:
- check
http.postandmcp-httphosts againstpermissions.networkusing the same parsed host (horae.contracts.url_host), never a second URL parser (horae.intentsdoes this forhttp.post, #20), and resolve names through the egress proxy so that a declared name cannot reach private or link-local addresses; - never follow redirects in a sink that makes a request (
http.post,mcp-http), or re-check the host of every hop withurl_hostagainst the samepermissions.network: a declared host must not be able to bounce a request to an undeclared one; - keep the run-wide number of proposed intents within
RunRecord.intents's bound,horae.contracts.MAX_RUN_INTENTS(256):horae.intents.MAX_INTENTSbounds one step only; - escape text before it reaches a format that interprets it: sinks writing Obsidian Tasks must
escape the emoji signifiers (
📅,⏰,✅,🔁…) in titles, not only Markdown; - install plugins with
git clone -- <repo>andprotocol.allowrestricted tohttps, even though the lockfile already only acceptshttps://URLs.
Rules only the pydantic models check¶
JSON Schema cannot express these; the models enforce them and the tests pin the difference:
run-record:changes[].intentis an index intointents;finished_atis not beforestarted_at(run and step records);intents[].applied_by,applied_by_stepandapplied_by_callare all set or all absent (the JSON Schema'sdependentRequiredchecks presence, the model also rejects an explicitnullnext to a value);pipeline_definitionis a valid pipeline namedpipeline, at most 64 KiB as compact JSON (decision 33).skill: twoinput_viewpaths may not overlap (one a prefix of the other) or disagree on whether a value is an object or an array (decision 39).task_fingerprint.idsis aninput_viewpath (or lies below one), andtask_fingerprintneedstask.createinintents(decision 67).plugin-manifest: the host of anmcp-httpruntime.urlis listed inpermissions.network; no tool inprovidesis a sink operation of the plugin's own sink or notifier namespaces (<ns>.read,<ns>.apply,<ns>.restore,<ns>.parent_exists,<ns>.identity, decision 36). Each key ofprovides.personal_fieldsis one ofsourcesortransforms, and a tool's paths may not overlap or disagree on a value's shape, a scan-onlyfree_text:path included (decision 68 K; the same rule for the lock'spersonal_fields).- Hosts (
permissions.network, everyhttpsURL): a label starting withxn--must be a valid IDNA A-label. It must round-trip through Python'sidnacodec (IDNA2003, so no runtime dependency) and decode to letters, marks, digits and-only. The second rule rejects what IDNA2003 allows but IDNA2008 does not, such as emoji (xn--ls8h) and symbols (xn--g6h); it approximates IDNA2008 rather than implementing RFC 5892 exactly. instance(horae.yaml): a bracketed IPv6 literal inbase_urlmust parse as an IPv6 address (the schema only checks its characters and, forhttp, thefc/fdprefix).task.createlink(decision 52 A): the host may not be an IP address (its last label is a number, as WHATWG reads it, after NFKC), and no character may be a supplementary-plane format character (tagsU+E0001,U+E0020-U+E007F, ...) or a lone surrogate. The pattern already refuses the Basic Multilingual Plane controls, format characters and separators, bracketed IPv6 and%in the authority.
Known validator differences¶
- Integral floats. JSON Schema
integer(andconst: 1) accepts2000.0; the models reject it. - Trailing newline with Python's
jsonschema. It evaluatespatternwithre.search, where$also matches before a final\n, so"Buy milk\n"passes^[^\x00-\x1f\x7f]+$. ECMA-262 validators and the models reject it. The patterns use no look-around and no\s/\d/\wshorthands, so they mean the same in ECMA-262 and Rustregex(pydantic); the test suite validates with ECMA$semantics. - Formats.
format(date,date-time) is an annotation unless the validator asserts formats (FormatCheckerin Python'sjsonschema, withjsonschema[format-nongpl]). Every date and date-time also has apattern, so a naive date-time fails either way; an impossible date such as2026-02-30fails only with format assertion (and always in the models). - Explicit
null. Optional fields acceptnullas "absent", in both. - Non-finite numbers. The models reject
NaNandInfinity; standard JSON cannot contain them.
Lockfile canonical form¶
Serializing a Lockfile sorts plugins by name and every permission list, so a diff of two lockfiles
shows only real changes. Reading accepts any order. The file's text is block-style YAML with sorted
keys and a trailing newline, after the file's own leading comment lines (horae.marketplace.lock,
decision 70): the same lock is always the same bytes.
Examples¶
examples/<name>/valid/ and examples/<name>/invalid/ hold passing and
failing examples for every schema. Each valid example passes the JSON Schema, validate_python and
validate_json; each invalid one fails all three. examples/pipeline/valid/daily-brief.yaml and
examples/plugin-manifest/valid/github.yaml are the PLAN.md §3.2 and §3.3 examples, verbatim (a
test checks this). All other examples are synthetic.
Decisions¶
Confirmed by the maintainer on 2026-10-28. PLAN.md left these open; each takes the most conservative option, so loosening one later is a compatible change.
- Intent names. §2.1 says
create_task,append_note,notify; §3.3 lists the closed setnote.create,note.append_section,note.replace_owned_block,task.create,task.update_status,notify.push,http.post. v1 uses the §3.3 names. - Intent fields are the minimum each sink needs:
task.createhastitle, a requiredfingerprint, optionaldueandtime(HH:MM, the ⏰ reminder;timerequiresdue);task.update_statususes the fingerprint as task id and the statusestodo,done,cancelled,snoozed(until, a date or date-time, is required forsnoozedand only allowed there);notify.pushhasbody, optionaltitleandlink;http.posthasurland a JSONbody(no headers). The core (horae.intents) accepts only plain JSON data inbody(string keys, finite numbers, nesting at most 64 deep) and caps its compact serialization (json.dumps(body, allow_nan=False, separators=(",", ":"))) at 1 MiB of UTF-8 (horae.contracts.types.MAX_BODY). - Fingerprint alphabet
A-Z a-z 0-9 . _ : -, 1–128 characters (fitssource:idkeys). - Note paths reject every segment starting with
., not only.obsidian/: hidden files and folders are never written by intents. - Text limits: title 500, heading 200, notification body 4096, note content 1 MiB.
- URLs are
httpsonly forhttp.post,mcp-httpruntimes (even to internal Docker service names),homepageand lockfilerepo. Host names must be lowercase and cannot be IP literals orlocalhost. - Notification links are
https://orobsidian://only. - Secret names reject the listed loader variables and reserve
HORAE_. Other variables that change process behaviour (NODE_OPTIONS,BASH_ENV,*_PROXY,SSL_CERT_FILE…) are left to the runtime's environment builder, which must own the full deny list. permissions.pathsis{ read: [...], write: [...] }of absolute paths. What they are relative to (the container's filesystem, the instance root, a vault mount) is open for #20/#51.permissions.networktakes bare host names (single-label names allowed): no port, scheme or wildcard. Any port on a declared host is allowed:http.posttohttps://hooks.example.org:8443/passes whenhooks.example.orgis declared. Ports are not part of the permission; restricting them would need a new, explicithost:portform.- Namespace prefix. Tools are
<namespace>.<tool>and skills<namespace>/<skill>. The namespace is not required to equal the plugin name, because PLAN.md uses prefixes that are not plugin names (coach.brieffromplugin-mcp-brief). How a namespace resolves to a plugin is for the engine to define. - "Implements" vs "proposes".
permissions.intentscovers both the intents a plugin may propose and those a sink may apply. Whether these should be two lists is open. - Trigger. Optional: a pipeline without one runs only from an external scheduler
(
horae run).cronis five fields separated by single spaces, of0-9 A-Z a-z * / , -(no@dailymacros), with an optional IANAtimezone(instance default otherwise). - One LLM step per pipeline is enforced (PLAN.md says "by default"); a later opt-out would be an explicit key.
on_unchanged_inputaccepts onlyskip: §2.2 forbids an LLM call on unchanged input.- LLM timeout.
timeout_sis optional; the core supplies a default. - Transforms in
provides. §3.1 lists sources, sinks, notifiers, skills and pipeline packs, but §3.2 uses plugin transforms (tasks.normalize), soprovides.transformswas added. - Remote runtime.
protocol: mcp-httpwith anhttpsurlwhose host is inpermissions.network.runtimeis optional so pipeline packs and skill-only plugins need none. - Manifest metadata. Optional
description(one line),license(SPDX expression, syntax only) andhomepage(https). No author or keywords. horae.lock. §4 lists its content (name, version, SHA, approved permissions) but not its syntax; the schema validates the parsed document (the example is YAML) and adds the gitrepo(https only). Permission lists are written sorted.- Run record. v1 requires
pipeline_digest(SHA-256, hex, of the canonical pipeline definition; the canonical form is fixed by the engine, seehorae.engine.canonical) andcontext(now, IANAtimezone, rendered templatevars). Optional:lock_digest,config_digest,input_hash, per-steperror/ timings / cappedstderr, LLMattemptandschema_valid, andviolations(egress_blocked,guard,undeclared_secret,undeclared_path;intent_skippedsince decision 60). Statuses: runok,noop,degraded,failed,undone; stepok,skipped,degraded,failed. A dry run has nochanges. Untrusted-content tagging is not part of v1.intents[].proposed_byis the proposing tool (<namespace>.<tool>) or, for intents of thellmstep, the skill (<namespace>/<skill>) (added with #17, a compatible loosening). $idhost.raw.githubusercontent.com/horae-dev/horae/main/schemas/…, which this project controls and which serves the files once merged. A custom domain can come later asv<N+1>.
Provisional decisions (#16, pending maintainer review)¶
Taken in #16 so that the loader could be built; each is the conservative option and can be loosened later without breaking a valid file.
horae.yaml(instance v1) is kept minimal; every key is optional.schema_version(1, decision 26),timezone(IANA, defaultUTC),state_dir(defaultstate, relative to the instance directory),models(alias →backendfrom the run-record list,model,base_url(decision 24) andsecret, the name of the secret holding the API key or token),plugin_defaultsandplugins(decision 26),secrets(dir, default/run/secrets, andrefs: secret name →{env: VAR}or{file: name}, a single file name insidedir; decision 25) andscheduler.mode(builtin, the default, orexternal). It never holds a secret value. Rules the loader (not the schema) checks: time zones exist (zoneinfo.available_timezones(), with thetzdatapackage as a runtime dependency so that the answer does not depend on the host),llm.modelaliases are defined, configured plugins are inhorae.lock(skipped whenhorae.lockitself is invalid), a pipeline'snameequals its file name.- Backends and endpoints (A).
ollamaandopenai-compatiblerequirebase_url;anthropicrequiressecret;claude-clineeds neither.base_urlis aBackendUrl:httpsis always allowed (any host name,localhostincluded, or an IP literal); plainhttponly to loopback (localhost,127.0.0.0/8,[::1]), private addresses (RFC 191810/8,172.16/12,192.168/16; IPv6 ULAfc00::/7) and single-label names (a Compose or Coolify service such ashttp://ollama:11434), where TLS is usually not available and the traffic does not leave the host or the private network. No user info (credentials belong in a secret), no fragment. The JSON Schema expresses the same rule (one pattern andif/thenfor the required keys). - Secrets come from files unless a reference says otherwise (B). A secret with no entry
in
secrets.refsis read from<secrets.dir>/<NAME>only. Environment variables are read only through an explicit{env: VAR}reference. This keeps a plugin that declares a secret name from pulling an arbitrary variable of the host environment, and steers deployments towards secret files, which a plugin cannot read through/proc/<horae-pid>/environ(see the #24 design note, "Not enforced until M5"). An explicit env reference to a variable that is unset or empty is an error. One trailing newline (\nor\r\n) is stripped from every value; a value that still contains\r,\nor NUL, or a file that is not a regular UTF-8 file of at most 64 KiB, is an error. Files are opened once, non-blocking (a FIFO cannot hanghorae doctor), and checked withfstaton that descriptor. schema_versionand plugin timeouts (C).horae.yamltakes an optionalschema_version: 1(trueand1.0are rejected, as everywhere).plugin_defaults(startup_timeout_s, default 10, andcall_timeout_s, default 30) applies to every plugin;plugins.<name>may override either. Every timeout is 1 to 600 seconds.Instance.plugin_timeouts(name)returns the effective pair for the #24 plugin host.horae doctor(D). Exit codes (kept by decision 37):0no problem,1problems found,2usage error,70internal error (EX_SOFTWARE; the doctor then prints only the exception type, never its message, traceback or locals, which may hold a resolved secret).--jsonprints{"schema_version": 1, "ok", "instance", "problems": [{file, line, column, severity, message}]};severityiserroror, since decision 38,warning(reported, not failing).- The environment deny list is the #24 host's (E).
SecretNamerejects only the loader variables of decision 8. The full deny list of the #24 design note (NODE_OPTIONS,BASH_ENV,*_PROXY,SSL_CERT_*,GIT_*, …) is enforced by the plugin host when it builds a child environment, not by the schema: it is about what a variable does in a child process, not about whether a name is a valid secret name. The #24SecretResolverprotocol should return aSecret(notstr), so values stay redacted until the host puts them in the child environment, and the host can redact every value fromSecretResolver.resolved(). - Problem positions (F). A problem points at the value when the value is wrong
(
scheduler.mode: cronpoints atcron), and at the key when a key is unknown, invalid or missing (a missing key points at its parent's key). A mapping key that is not a valid name is shown as<key at line N>, never echoed, since it may be a secret pasted in the wrong place. Messages never show a regular expression, and a union (a pipeline step, a secret reference) gives a single problem, e.g.unknown step kind 'colect' (expected one of: collect, transform, llm, act, notify). -
Intent routing in the run record (#17, maintainer decision D1). Following ADR 0002, sources, transforms and the LLM step propose intents;
act/notifyentries are never called during a run, they name the sink or notifier that applies the intents later (#21/#22). Each recorded intent says which entry:intents[].applied_by(the entry's<namespace>.<tool>),applied_by_step(its step) andapplied_by_call(its index in the step). The three are optional in v1 (a compatible addition) but go together, and the engine sets them on every intent it records; an applier must refuse an intent without them.llm[].intentsrecords the raw intents returned with the response, before the core fills a target from the entry's parameters, for replays and for reuse on unchanged input (D2).input_hashis the LLM step's cache key (horae.engine), set only when the LLM output was accepted or reused. The routing and binding rules are the engine's, documented inhorae.engine.executor; in short:- every
actentry has a requiredmode(create,append-section,replace-owned,tasks,post); the note modes bindpathandpostbindsurl, compared as exact strings (no case, Unicode or URL normalisation); - a
notify.pushlinkis routed only to anotifyentry whose trustedlink_prefixit falls under; withoutlink_prefixa proposed link is never routed. A prefix is anhttps://orobsidian://link with a host, no user info, query or fragment, and a clean path that ends with/(e.g.obsidian://vault/Main/), elseparams_invalid. Both are parsed (urlsplit), not compared as strings: same scheme, the same authority (since decision 52 B, anhttpshost compares case-insensitively, without one trailing dot, with:443equal to no port; anobsidian://netloc exactly), and a link path under the prefix path (case-sensitive) whose rest has no empty,.or..segment, backslash, or%2e/%2f/%5c/%25(so no/notes/../admin, nohost.evilorhost@evil). The link may add its own query and fragment; - a
task.update_statusis routed only if itstaskfingerprint appears as a string value in the run's collected input;task.createbinds no target but its optionallink, which (decision 52) is routed only to amode: tasksentry whose trustedlink_prefixit falls under, by thenotify.pushrule above; - two entries that may apply the same type to the same target make every such intent
intent_ambiguous, by design: untrusted data never chooses between trusted entries; - the proposer's permissions are checked before routing (
intent_rejectedwins); - the run record model checks that a route names a real, later entry of the right kind that lists the intent.
Routing binds where an intent goes, not what it says: note content, task titles, notification titles and bodies, and
http.postbodies stay untrusted text, which appliers must treat as data. Reusing an unchanged input re-proposes identical intents,notify.pushincluded, so appliers (#21/#22) must deduplicate notifications (e.g. byinput_hashand intent); reused intents that no longer route are a cache miss and the LLM is called. - every
Provisional decisions (#19, pending maintainer review)¶
- Run lifecycle (#19).
horae.yamltakes an optionalruns.timeout_s(default 900, 1 to 86400 seconds), the run timeout. Per-call limits stay where they are:plugin_defaults.call_timeout_sfor tool calls (the #24 host) and the pipeline'sllm.timeout_sfor the LLM step (the engine). Other rules of the runner (horae.runner), which are not part of a schema (A to G are provisional maintainer decisions):- run ids are
<UTC start, %Y%m%dT%H%M%S%fZ>-<pipeline>-<6 hex>, so they sort by start time and matchRunId; a collision (RunExists) is retried once with a fresh id; - (B) liveness is an OS advisory lock. A run holds
flock(LOCK_EX | LOCK_NB)on<state_dir>/locks/<pipeline>.lock(directory 0700, file 0600, openedO_CLOEXEC | O_NOFOLLOW) for its whole life; the kernel releases it however the process ends. A busy lock is retried for 0.2 s, then the run is refused withPipelineLocked, naming the running run read from the store (its start, pid and host) when there is one; nothing is written. With the lock held, anyrunningrow of that pipeline is dead by definition and is abandoned (failed, no record, journal kept) as a compare-and-set on its id and last heartbeat (Store.abandon_run(heartbeat_before=...)), thenbegin_run. The store's unique index on running runs stays as a second guard (PipelineBusyis reported asPipelineLocked). Heartbeats (every 10 s) stay for observability but no longer decide liveness: there is no stale delay and no pid or host check. Local filesystems only (no NFS or SMB, as ADR 0006 already requires for the database). POSIX only: Linux (the container target) and macOS (development); withoutfcntl(Windows) taking a lock raisesLocksUnsupported(Windows is unsupported, nomsvcrtfallback); - (G) recovery covers only the pipeline being started; other pipelines are recovered
when they next start.
horae runsshows arunningrow whose lock is free asrunning (stale?)("stale": truein--json), checked without waiting and read-only (a missing lock file is a free lock; one that cannot be opened is not flagged); - (A) dry runs take the lock too;
- (C) the heartbeat interval (10 s), the stop grace period (5 s) and the lock retry
(0.2 s) are constants, not
horae.yamlsettings. A heartbeat waits at most 100 ms for the write lock (HEARTBEAT_BUSY_TIMEOUT_MS, on a second connection), then skips the beat; heartbeat failures of any kind are logged once per run (exception type only) and never stop the run; - (D) timeouts. Past
runs.timeout_sthe run is cancelled and given 5 s to stop. If it stops, its partial record is savedfailed(the interrupted stepfailedwith error kindtimeout, later stepsskipped) andRunTimedOut(record)is raised. If it finished anyway after the deadline (a step ignored the cancellation), it is savedfailedwith the errorthe run timed out after N s (it finished after the deadline), neverok. If it still has not stopped, the run is abandoned with the errortimeout: the run timed out after N s and its step did not stop within 5 sandRunTimedOutis raised withrecord = None; - (F) cancellation. When the caller cancels
Runner.run(Ctrl-C, orasync with asyncio.timeout(...)), the partial record is saved (kindcancelled; a run cancelled before its first step gets a minimal record, every stepskipped, errorthe run was cancelled before it started), passed to theon_recordcallback, and a plainasyncio.CancelledErroris re-raised, soasyncio.timeoutturns it intoTimeoutError.RunTimedOutis aRunnerError, not aCancelledError. The same 5 s grace applies (then the run is abandoned withcancelled: ...). A cancellation that arrives while the heartbeat stops is not swallowed; - a crash (any other exception) abandons the run with
run crashed (<ExceptionType>), never the exception's message; if that abandon fails, it is logged (types only) and the next run of the pipeline recovers the row. A row abandoned by someone else while the run runs is noticed by the heartbeat, the next step write or the final save: the run stops withRunLost; - clocks: timestamps and run ids use the wall clock, the run timeout the event loop's monotonic clock. A wall-clock step only shifts recorded times (and may reorder run ids started across it); since liveness is the lock's, it cannot make a live run look dead;
- the template time zone is the pipeline trigger's
timezonewhen set, elsehorae.yamltimezone; - (E) the store is
<state_dir>/horae.db.horae runslists runs (--pipeline,--status,--limit,--json) with the exit codes of decision 27. It opens the store withStore.open(path, read_only=True): it never creates the store or any file (no-wal/-shmwhen no writer is active), never switches the journal mode and never migrates; a schema older than this Horae exits 1 (SchemaTooOldError: "runhorae runonce to migrate it"), a newer one too (SchemaTooNewError), and so do permission and other OS errors. The table has anERRORcolumn: the run's error on one line, control and bidi characters collapsed, at most 60 characters.--jsonprints{"schema_version": 1, "instance", "runs": [{id, pipeline, status, stale, dry_run, abandoned, started_at, finished_at, duration_s, cost: {usd, tokens_in, tokens_out}, error}]}, whereinstanceis the resolved absolute path anderroris the run's full error, which carries step messages as capped by the engine (4096 characters).
- run ids are
Provisional decisions (#21, pending maintainer review)¶
- Dry-run diff (#21).
horae.applyplans what applying a stored run would change andhorae diff <run-id>shows it; nothing is applied (that is the journal's, #22). The rules (D1 to D8 are provisional maintainer decisions):- (D1) the core owns note conventions. The
Sinkport (horae.apply.sink) has two operations:read(call) -> bytes | None, a read-only fetch of anote.*intent's current target (None: no such note), andapply(call, *, expected_before_sha256) -> Applied, a compare-and-swap for #22 (the SHA-256 of the bytes the change was planned against,Nonemeaning "must not exist"; a mismatch changes nothing and raisesSinkError("target_changed")). There is no sink-side preview: the core computes each note change fromread()andhorae.apply.notes, and builds task, notification and HTTP previews from the intent alone, without calling the sink, so a plugin cannot show one change and make another. What a sink returns is type-checked at runtime (bytesorNone, elsepreview_invalid). Over MCP note bytes travel base64-encoded, at mostMAX_MCP_NOTE_BYTES(about 5.95 MiB, decision 36;note_too_large). The sink receives a deep copy of the intent and its entry's parameters; - (D2) Horae never creates content in a note it does not own. A note is owned when
its file name ends in
.assistant.md, decided on the path the sink resolved without following symlinks.note.create(note_existsif present) andnote.append_section(note_missingif absent) need an owned note.note.replace_owned_blockcreates a missing note or block only in an owned note; on any other note it only replaces a block that already exists (not_ownedotherwise); - markers and line breaks. A block is the lines from
<!-- horae:begin <block> -->to<!-- horae:end <block> -->, both included; a marker may end the note without a final newline. One case-insensitive recogniser (horae:(begin|end), optionally with a block name) serves both directions: in a note, every line naming the block counts and must be exactly one canonical begin line followed by one canonical end line (surrounding spaces and a final\raside), elseblock_ambiguous; in untrusted text (content, heading) it must not appear anywhere (content_has_marker). Untrusted text may break lines only with\nor\r\n: a lone\r, U+0085, U+2028 or U+2029 is refused (content_line_break). Inserted lines use the note's line ending (that of its first line,\nfor a new or one-line note); the rest of the note is kept byte for byte; - targets (for #22 too). A sink resolves a note path without following symlinks on
any component (
symlink), refuses a file with more than one hard link (hard_link) and anything but a regular file (not_a_file), and decides ownership on that path. The built-inLocalSinkwalks the path withdir_fdandO_NOFOLLOW, opens the noteO_RDONLY | O_NOFOLLOW | O_NONBLOCK | O_CLOEXEC, checks it withfstatand reads from the descriptor; a name that is too long or a parent that is not a directory isnot_a_file, a permission or other OS errorunreadable, a path holding:is refused (path_invalid). POSIX only: Windows is unsupported.apply(#22) must use the same resolution, on the descriptor it writes through; - chaining. Several intents on one note are planned in run order, each against the
bytes the previous one leaves (
followsnames it; the note is read once), which is the order #22 applies them in, sobefore_sha256is exactly theexpected_before_sha256of thatapply. An intent that cannot be planned does not change what the next one sees; - (D3) which runs.
ok,noopanddegradedruns are planned. Afailed(run_failed) orundone(run_undone) run is refused, and so is a run whosechangesis not empty (already_applied: its journal, #22, says what changed); - (D4)
horae diffexit codes:0planned without problems,1configuration or store problem,2usage error,3unknown, unfinished or refused run,4planned with problems (some intents cannot be applied),70internal error. A notification already sent (duplicate) is information, not a problem. With--json, an error is a JSON object on stdout,{"schema_version": 1, "error": {"kind", "message"}}(kindsconfig_invalid,store_error,unknown_run,internal), and a refused run is the change set with"refused": {"kind", "message"}; without it, errors go to stderr. Text output escapes every Unicode Cc, Cf, Zl and Zp character except tab; JSON output is ASCII and strict (a non-finite number becomes a string); - (D5) what a dry run may write. User data never: no vault change, no notification,
no remote write. Horae's own state database (
<state_dir>/horae.db) is not user data:horae run --dry-run(#26) records its run there, and the write guard oftests/test_dry_run.pyallows only that path (and its-wal,-shm,-journal) besides the test's scratch directory.horae diffitself opens the store withStore.open(path, read_only=True): it creates, migrates and changes nothing (an OS error opening it exits 1). The guard covers Python-level writes, metadata changes, sockets, name resolution, SQLite connections and process creation; writes made below Python (ctypes, C extensions) and plugin subprocesses (#24's sandbox) are out of its scope; - (D6) the vault is given with
--vaultonly (no environment variable, nohorae.yamlkey) until plugin sinks exist (#24); without it note intents arevault_unsetproblems; - (D7) notification deduplication.
dedupe_keyis the SHA-256 (canonical JSON) of the pipeline, the routing entry (applied_byand its recorded parameters), the run'sinput_hash(or, without one, its id), the intent, and its occurrence index (how many identical entry and intent pairs precede it in the run). A reused unchanged input re-proposes the same keys, while two identical notifications of one run are both sent. The applier (#22) records a key once sent (Store.record_notification) and skips it afterwards; the key reaches the notifier asSinkCall.dedupe_key; - (D8)
horae diffships in #21;horae run --dry-runprints the same change set (#26, decision 37).
- (D1) the core owns note conventions. The
Provisional decisions (#23, pending maintainer review)¶
-
Replay (#23): run record extensions and
horae replay. Compatible v1 additions, all optional, so records written before them stay valid (they are only not replayable). The engine (horae.engine.execute) writes them; D1 to D6 are provisional maintainer decisions:- (D1)
pipeline_definition: the canonical pipeline definition that ran (horae.engine.canonical_pipeline, the input ofpipeline_digest), at most 64 KiB as compact JSON (MAX_PIPELINE_BYTES; omitted when larger). It is namedpipeline_definitionbecausepipelinealready holds the pipeline's name. The models check that it is a valid pipeline namedpipeline; replay checks that its digest ispipeline_digest. Replay runs this definition, so a run replays as it ran after its file was edited (noted); without it, only a current definition with the same digest replays, else "pipeline changed" (unless--against-current); - per-call raw proposals (finding 1):
inputs[].call(the source's index in its step) andinputs[].intents(the raw intents it returned, any JSON shape, absent when none); a collect source whose proposals failed the step is recorded too. A failed source's entry in the stepoutputgainscall. Atransformstep that ran hassteps[].calls: [{call, ref, params, input_hash, intents?, error_kind?}]: each call made,input_hashthe SHA-256 of the canonical JSON of the input it was given (intermediate outputs are not recorded). Replay answers each call by(step, call)and the engine re-validates and re-routes the raw proposals, so a target omitted by the proposer is filled again from the (possibly edited) entry, and a rejected or unroutable proposal fails the replayed step as it failed the run; - engine-owned LLM fields (finding 2):
llm[].model_alias(the pipeline's alias),input_hash(SHA-256 of the attempt's input; not the cache key, which isinput_hashof the run),repair(the errors sent with the attempt) andschema_errors(each capped at 4096 characters, at most 256; the repair retry is sent these capped errors).requeststays whatever the backend reports, for information; - (D3)
models(alias to concrete model, as given to the engine) andlock_digest/config_digest: the engine records what its caller passes; the runner (#19) passesInstance.lock_digest()(SHA-256 of the canonical JSON of the validatedhorae.lock) andInstance.config_digest()(SHA-256 of the canonical JSON of the validatedmodelsandpluginssections ofhorae.yaml, defaults filled in; the time zone, state directory and timeouts are not part of it). Replay uses the recordedmodels(the caller's only when the record has none, noted). A recorded digest that differs from the current instance's is an error, or a note with--against-current; - (D5)
plugins[].provides: the tools and skills of the pipeline the run resolved to that plugin, sorted.horae.replay.LockRegistryresolves a ref to the plugin the run resolved it to when that plugin is still locked, else to the locked plugin named after its namespace, with the locked version, commit and permissions. So the PLAN.md §3.2 brief (coach.brieffrommcp-brief, the skill frompack-daily-brief) replays from the CLI. Replay asks its registry once, up front, for every ref of the pipeline and runs the engine on that frozen snapshot; aPluginRegistrydoes no I/O beyond local files and starts no process;horae replaynever uses a live plugin host; - comparison: canonical pretty JSON of the intents (routing fields included), plus a
summary of the run status,
input_hash, step kinds, statuses and error kinds, counts, violation kinds and plugin versions (withprovides). Anundonerun's status is compared as it was before the undo, derived from its steps (noted). Messages, timings,stderrand cost are not compared; - (D4, refined by finding 7)
horae replayexit codes:0identical,1configuration or store problem (an invalid instance, a store that cannot be opened, a schema older or newer than this Horae: likedoctorandruns),2usage error (a bad option, an unknown run, no store at the path),3not comparable (the pipeline,horae.lockorhorae.yamlchanged without--against-current, an unresolved plugin, a call the record cannot answer, a record that is not a valid v1 record or predates these fields),4different,70internal error (its type only).--jsonprints{"schema_version": 1, "run_id", "pipeline", "outcome", "identical", "against_current", "definition", "pipeline_digest", "lock_digest", "config_digest", "error", "mismatches", "notes", "intents_diff", "summary"}with every key also on errors (nullor empty), each digest as{recorded, current, changed}; - (D6)
horae replayopens the store withStore.open(path, read_only=True)and never creates it; - (D2) these extensions land with the replay itself (#23), not in a separate change.
Remaining limits: per-call
stderrand failure messages beyond their recorded excerpt are not reproduced (messages are not compared), and only the first call of a multi-calltransformstep has its input checked (later calls get the previous call's output, which is not recorded). - (D1)
Provisional decisions (#22, pending maintainer review)¶
- Journal and undo (#22). No contract changes: the run record already has
changesand theundonestatus. The rules (horae.apply.apply,horae.apply.undo, the runner):- apply in the runner.
Ports.sinks(aSinkRegistry) is the runner's apply port. After the engine finishesok,noopordegraded(not a dry run, not timed out or cancelled), the runner plans the run (plan_changes, with the notifications already sent) and applies it (apply_changes) while its row is stillrunningand its heartbeat still beats, then saves the record withchanges(indices intointents, with the core's target: note path, task fingerprint,http.postURL, or the notifier's tool). WithoutPorts.sinksnothing is applied. The apply is not underruns.timeout_s; each sink call (the plan's reads, the apply's read and apply, undo's read and restore) is bounded byplugin_defaults.call_timeout_s(kindtimeout; the change stays "maybe applied"). A run whose caller cancels it after its steps finished but before the apply is savedfailed("cancelled before apply", nothing applied): neverokwith intents that were not applied; - one apply at a time (D6). The runner's apply phase and
horae undohold the instance-wide apply lock<state_dir>/locks/_apply.lock(the sameflockhelper as the pipeline locks; a pipeline name never starts with_), in addition to the pipeline lock. The runner waits for it at mostAPPLY_LOCK_WAIT_S(30 s), then fails the runapply_lockedwith nothing applied; undo does not wait (apply_locked, exit 5 since decision 37); - journal first. For each planned change in intent order:
journal_append(with the sink,applied_by, where it writes,sink_identity, and for a note its bytes before and after), thenSink.apply(a compare-and-swap on the plannedbefore_sha256; the core re-reads the note and recomputes the bytes first), thenjournal_mark_applied. Notes are undoable; task changes, notifications and HTTP calls are journalled withundoable = 0. A notification whosededupe_keywas already sent (Store.get_notification) is skipped; once sent,record_notificationand the mark share one transaction (a crash in between can send it twice, never lose it). An unchanged note is skipped; - failures (D1). A plan with problems or a refusal applies nothing (
plan_invalid,plan_refused). Otherwise the first failing change stops the apply: earlier changes stay applied and recorded, later ones are not applied, and the run is savedfailedwitherror=<kind>: intent <i> (<sink>) could not be applied: <message>; <n> change(s) applied before it, the rest not applied(kindstarget_changed, the sink'sSinkError.kindwhen it matches^[a-z_]{1,32}$,timeout,host_errorfor any other exception or kind, whose message is dropped,apply_mismatchwhen the sink reports other bytes than planned,no_sink). There is no automatic rollback: a run that fails mid-apply staysfailed, andhorae undois the remedy. A crash during the apply abandons the run (decision 31); its journal remains. Onapply_mismatchthe bytes the sink reports are journalled (actual_after_sha256, a blob), and undo accepts them as "as the run left it"; - the store (migration 3, unreleased, so edited in place) adds
journal.applied_by(undo finds the sink even for an abandoned run, which has no record),journal.sink_identity(where that sink writes),journal.actual_after_sha256andjournal.undo_overwrote_sha256(both blobs;prune_runskeeps every referenced blob), and an index on(target, id)for the newer-run check. All are NULL for older rows; - sink identity. A sink may have an
identity(at most 512 characters;horae.apply.sink_identity):LocalSink/LocalFileSinkuselocal:<st_dev>:<st_ino>:<real path>of the vault,FixtureSinka fixed id. Undo refusessink_mismatch(exit 1, also under--force, before reading anything) when the sink an entry's tool resolves to now has another identity than the one recorded (e.g.--vaultnames an empty or another vault). A note missing together with its directory is never "already restored" when a change of it was applied (parent_missing:RestorableSink.parent_exists). Over MCP the identity is the plugin's (decision 36); - undo restores bytes, not intents.
RestorableSinkaddsread_target(target),parent_exists(target)andrestore(target, content, *, expected_sha256)(content=Noneremoves the note), a compare-and-swap. A syntheticapplywas rejected: the closed intent set has no "write these bytes" or "delete" intent, and an abandoned run has noSinkCallto rebuild. Entries are grouped per (resolved sink identity, note) in sequence order, so two tools of one sink editing one note are one group: one write of the bytes the note had before the run's first change of it (a note the run created is removed), latest note first. Each note is read first: holding its original bytes it is already restored (resumability after a crash; also a change journalled but never applied); with the digest of the last applied entry'safter(oractual_after), or of a later entry stillapplied = 0, it is restored; otherwise it changed since and the whole undo is refused before any write, unless--force, which keeps the overwritten bytes as a blob (undo_overwrote_sha256, reported). Once written, the note's entries are marked undone. When every undoable entry is undone, a run with a record is savedundone. Undoing an undone run is a no-op; a running run or a dry run is refused; - last in, first out per note (D8). If a later run (any pipeline) has an applied, not
undone change of the same note through the same identity, undo refuses
newer_run(exit 4) naming those runs, unless--force, which reports them (later_runs); - crashes (D3, D4).
horae undoholds the pipeline lock, so the pipeline'srunningrows are dead: it abandons them first with the runner's helper (horae.runner.recover_pipeline, a compare-and-set on the last heartbeat), so a run killed mid-apply can be undone at once. An abandoned run staysfailed(the store's constraint), its entries undone. A run with no undoable entry at all is refusednothing_to_undo(exit 3) and its status is left as it is. Directories created by apply are kept; - not undone (D2, D7). Task changes are not undone (no recorded before-state yet; left to the tasks story). Notifications stay sent and their dedupe keys are kept, so an undo never causes a surprise re-notification;
horae undo <run-id>(--vault,--force,--json) holds the pipeline's lock and the apply lock, opens the store read-write (migrating it) and writes withLocalFileSink(provisional until #24:LocalSink's resolution, every file-system call in a worker thread; nothing is created before the compare-and-swap passes, then missing directories are made relative to the parent descriptor and each new entry's directory isfsynced; the new bytes go to.horae-<12 hex>.tmp(O_CREAT | O_EXCL | O_NOFOLLOW, the note's mode,fsync), and just beforeos.replacethe note's device, inode, size and mtime are checked against the compare-and-swap read; a removal renames the note to.horae-<12 hex>.old, hashes what it renamed, then unlinks it or puts it back withlink+unlink, never over a new note; stale.horae-*.tmpfiles older than an hour are swept from touched directories; the remaining check-then-rename window is not closed against concurrent editors).LocalSinkstays read-only forhorae diff. Exit codes followhorae diff:0undone (or nothing left),1configuration, store, lock or sink problem, orsink_mismatch,2usage,3unknown, running or dry run, ornothing_to_undo,4refused because a note changed or a later run changed it (--force),70internal.horae replayused other codes (2 unknown run, 3 not comparable); #26 aligned them (D9, decision 37: an unknown run is 3 everywhere, and the pipeline and apply locks are 5).--jsonprints{"schema_version": 1, run: {id, pipeline, status, abandoned}, force, complete, marked_undone, refused, notes: [{target, applied_by, sink_identity, intents, action, status, forced, expected_sha256, found_sha256, later_runs, overwrote_sha256}], not_undoable: [{intent, intent_type, target, applied_by, applied}], problems}; errors are{"schema_version": 1, "error": {kind, message}}.
- apply in the runner.
Provisional decisions (#24, pending maintainer review)¶
-
Plugin host v1 (#24, design note and maintainer answers on #85). Contract changes, both compatible v1 additions:
- per-call timeout (answer 8). A plugin call has a third, explicit form,
{tool: <ref>, params: {...}, timeout_s: N}(ToolCall;paramsoptional,timeout_s1 to 600 likeplugin_defaults.call_timeout_s). It cannot be confused with the mapping form, whose single key is a tool ref (always with a dot). The suggested{ref: {params: {...}, timeout_s: N}}was not used: it is ambiguous with a tool whose parameters are namedparamsortimeout_s. Withouttimeout_sthe explicit form is the same call as the mapping form and has the same pipeline digest; with one, the canonical form keeps{tool, params, timeout_s}(a timeout changes how the call runs). When omitted,plugins.<name>.call_timeout_s, thenplugin_defaults.call_timeout_sapply. The engine passes it toToolCaller.call(..., timeout_s=); secret_in_outputviolation (answer 4). The maintainer's answer "add the secrets from the output" is read as: a secret value (or its base64, hex, percent or JSON encoding) found in a tool's output or intents is redacted ([REDACTED:<NAME>]) and recorded as asecret_in_outputviolation; the step does not fail. Redaction covers every secret the instance resolved (SecretResolver.resolved()), in stderr, error messages, outputs and intents. A replay leaves this kind out of the compared violations (it describes the live process).
Rules of the host (
horae.plugins.host), not part of a schema: -mcp>=2.3,<2.4is a core dependency (answer 1). The host spawns the process itself (answer 2;stdio_clientcopies host variables) and keeps the SDK'sClientSession, which advertises no client capability and refuses sampling, roots and elicitation; - the child environment is exactlyPATH(fixed),HOMEandTMPDIR(empty per-run directories),LANG=C.UTF-8,TZ(the instance time zone) and the declared secrets (answer 3), with the deny list of decision 28 (env_unsafe); - one process per plugin per run, lazily started; one in flight per process; after a timeout, crash or protocol failure the process group is killed and the plugin may be started once more in the run, thenplugin_unavailable(answer 6); - intents travel in the result's_meta["dev.horae/intents"](answer 5); the untrusted input of a transform in the request's_meta["dev.horae/input"], so the arguments are the trusted parameters only. Data isstructuredContent, else a single text block that parses as JSON (answer 9); - parallelcollect(answer 7). The calls of acollectstep run concurrently (at most 8 in flight, started in declaration order); results, snapshots, stderr, violations and intents are recorded in declaration order, so records and replays do not depend on timing. Every source of the step is called and recorded, even when an earlier one's proposals fail the step (sequentially, the later ones were not called). Transforms stay sequential (each feeds the next);act/notifyentries are never called; -/proc/<pid>/environ(answer 10): Horae never adds a resolved secret to its own environment, and secret files (decision 25, the default) are recommended over{env: VAR}references, whose values a same-user plugin can read on Linux. The proper fix is the M5 container isolation (#50, #51).Security review of the implementation (provisional, pending maintainer review): - A. Sibling plugins. Plugins run as the same user, so while two run at once one can read the other's environment, hence its declared secrets (
/proc/<pid>/environon Linux,ps ewwon some systems). Accepted as a pre-M5 risk, mitigated by the first-party-only rule of the "declared" tier, and narrowed: the engine releases each plugin right after the last step of the plan that calls it (or as soon as the run stops early), through an optionalrelease(plugin)method of theToolCaller(ReleasingToolCaller);PluginHost.releasestops its process, so a plugin is not alive during later steps that do not use it. A released plugin called again starts afresh without using its one restart; a failingreleaseis ignored; - B. Complete redaction from the first call. When the host opens it resolves every secret declared by every locked plugin and everysecrets.refsentry (one that cannot be resolved is skipped; the plugin needing it fails withsecret_missinglater), so redaction does not depend on which plugin started first (SecretResolver.referenced()lists the refs); - C. More encodings. For secrets of at least 8 bytes the redactor also matches the lower- and upper-case hex, and misaligned base64 (both alphabets) of the value embedded in a longer stream at byte offsets 1 and 2 (an HTTP Basicuser:<secret>header): only the characters that depend on the value alone,ceil(8k/6)tofloor((8k + 8n)/6)for offsetkandnbytes, so up to 4 bits of the value can stay visible on each side; - D. Short secrets and keys. Encoded and partial forms are used only for secrets of at least 8 bytes. A shorter secret is matched by its raw value only, in every channel (stderr, messages, string leaves), where it is bounded (not next to an ASCII letter or digit:token=abc123and<ref>: abc123match,xabc123ydoes not), and as a whole JSON string or number; an error message is redacted whole first (a secret may contain or straddle:), then the body of the redacted<ref>: <message>is also matched as a whole value. The host logs a warning (name only) for each secret under 8 bytes it redacts, since its encodings are not redacted. Superseded for short secrets by decision 43 H (#53): a secret under 8 bytes is now refused when it is resolved, so the bounded raw-value matching and this warning are gone; the rest of D (keys, messages, overlaps, numbers) stands. Object keys are never rewritten: a key holding a secret fails the call withoutput_invalidand nothing is stored. When the matches of two secrets overlap, only the leftmost one is replaced (documented limit). A JSON number whosejson.dumpsis a secret becomes the token string; the SDK's own log records (mcp.*,client,server) are scrubbed when created: message redacted, arguments, traceback and stack dropped (every logger since decision 43 E); - E. umask. Every plugin process starts with umask0o077; - F. Stderr window. The per-call stderr window keeps its quiet-window heuristic (stderr and stdout are separate pipes, so nothing orders them); tests wait for a sentinel line instead of relying on timing. What a process wrote before it died between two calls goes with the next call; what it wrote after its last call is kept, redacted, inPluginHost.leftover_stderr; - G.runtime.commandpinning. The lock pins version, commit and permissions, not the manifest'sruntime.commandor the plugin's files; pinning them is M4 (#44, #46). A relative command must resolve (symlinks included) inside the plugin's directory, and is passed as an absolute path; - the deny list (decision 28) also coversGLIBC_TUNABLES,JAVA_TOOL_OPTIONS,JDK_JAVA_OPTIONS,CLASSPATH,PERL5LIB,PERLLIB,RUBYLIB,SSLKEYLOGFILE,OPENSSL_*,NODE_EXTRA_CA_CERTS,NODE_TLS_REJECT_UNAUTHORIZED,LOCPATH,GCONV_PATH,TZDIR,LANGUAGE,SHELLOPTS,PS4,GODEBUG,MALLOC_*,UV_*,PIP_*,NPM_CONFIG_*andVIRTUAL_ENV; - calls to one plugin are serialised, so N calls to it in one step can take N times the call timeout; the run timeout (#19) bounds the whole. Group termination cannot reach a descendant that left the group (setsid/setpgid), and the finalkillpgafter the leader is reaped has a (very unlikely) PID-reuse race; both are M5's (#50, #51). - per-call timeout (answer 8). A plugin call has a third, explicit form,
Provisional decisions (#25, pending maintainer review)¶
- Plugin sinks, fixture plugins and the walking skeleton (#25). One contract rule (the
manifest's reserved sink operation names, a pydantic-only rule: the generated schemas do
not change). The rules (
horae.plugins.host.sink,horae.plugins.builtin,horae.runner.open_ports):- sink operations by convention. An
act/notifyentry's tool (<ns>.<tool>, inprovides.sinksorprovides.notifiers) is never called. The core applies the intents routed to it through five tools of the same plugin, named<ns>.read,<ns>.apply,<ns>.restore,<ns>.parent_existsand<ns>.identity(horae.contracts.plugin.SINK_OPERATIONS), which the plugin lists intools/listbut not inprovides, so no pipeline step can call them (the engine only calls provided tools); the core calls them withPluginHost.call_operation(same process, timeouts, restart and redaction as any call).McpSinksis theSinkRegistry(Ports.sinks): oneMcpSinkper (plugin, namespace); - reserved names. The manifest contract refuses a plugin that provides
<ns>.<op>for an operationopand one of its own sink or notifier namespacesns;HostRegistryrefuses any plugin providing a sink operation name of any installed plugin's namespaces (and a manifest built without validation).call_operationonly callstool == f"{ns}.{op}"withopinSINK_OPERATIONS,nsa sink or notifier namespace of that plugin andtoolprovided by no plugin (tool_missingotherwise): it is not a way to call arbitrary unprovided tools; - the core computes the bytes (D1 of decision 32). For a
note.*intentMcpSink.applyreads the note (<ns>.read), checks the planned SHA-256 (target_changed), computes the new bytes withhorae.apply.notes.note_afterand sends them to<ns>.applywithexpected_before_sha256: the plugin only writes them, atomically, if the note still has that digest, and reports the digest of what it wrote. Other intents are passed through (contentandexpected_before_sha256null).restoreis the same compare-and-swap for undo (content: nullremoves the note); apply_mismatchover MCP has noactual_after. A sink reporting another digest than the planned one fails the change withapply_mismatch; only the digest came back, not the bytes, so the journal entry keepsapplied = 0withoutactual_after, andhorae undotakes the note for "changed since": restoring it needs--force(which keeps the overwritten bytes in the journal, decision 34);- double read (accepted).
apply_changesreads a note to check it against the plan, andMcpSink.applyreads it again to build the bytes it sends: two<ns>.readper note change. The adapter never sends bytes computed from a read it did not make itself, notes are small, and merging the reads would couple the adapter to the apply phase; - one note-size cap over MCP. Note bytes are standard base64, at most
MAX_MCP_NOTE_BYTES= (MAX_MESSAGE_BYTES8 MiB − a 64 KiB envelope margin) × 3/4 = 6,242,304 bytes (about 5.95 MiB) decoded, either way (note_too_large; the built-inLocalFileSinkkeeps 16 MiB). A sink sends each result once, asstructuredContentwith a short text block (no second copy of the payload). The cap is checked before encoding on both sides:McpSink.apply/restorerefuse larger content before the call, andfile-sink.readof a larger note returnsnote_too_large(never an oversized message, which would cost the plugin its process withoutput_too_large). Malformed results areoutput_invalid. A sink error is a result{"error": {"kind", "message"}}: the kind must match^[a-z_]{1,32}$(elsehost_error), the message (already redacted by the host) loses its control and format characters and is capped at 500 characters. A host failure becomesSinkErrorwith the host's kind (timeout,plugin_crashed,tool_missing…); secret_in_outputfrom sink operations. It is logged by secret name only (the host redacted the value) and kept byMcpSinks;apply_changesadds those collected during a run (the runner's diff and apply) toRunRecord.violations(McpSinks.take_violations, deduplicated, at most 256 in all). Outside a run (horae undo, a dry run's diff built outside the runner) there is no record: they are only logged;- trusted configuration.
horae.yamlhas no per-plugin configuration in v1, so every sink operation receivespaths, the plugin's path permissions as approved inhorae.lock, and every tool call carries them in_meta["dev.horae/paths"].file-sinkwrites to its singlepaths.writeentry (vault_unsetwithout one,config_invalidotherwise); its manifest asks for no path, since where the vault is is the user's choice, granted in the lock. This channel stays for v1: M4'shorae plugin add(#44) must carry thepaths.writeentry into the lock it writes (a per-plugin configuration inhorae.yamlis a later decision); - identity (decision 34).
mcp:<plugin>:<what <ns>.identity returns>(its SHA-256 when longer than 512 characters).sink_identitystays synchronous, with a mandatory asynchronous prepare done by the core: a registry may haveprepare(tools), whichhorae.apply.prepare_sinksawaits before any identity is read, with only the tools about to be used (apply_changes: the run'sapplied_bytools, so anotify.pushortask.*change, which reads nothing first, still journals its identity;undo_run: the journal's undoable entries). No caller prepares by hand. Until it is fetched the identity raisesidentity_unknown. Definitive failures (identity_invalid,vault_unset,config_invalid) are cached; any other kind (host kinds: a timeout, a crash) is retried once on the next prepare, then cached.file-sinkreturnslocal:<st_dev>:<st_ino>:<real path>of its vault, so undo refuses another vault (sink_mismatch). The prefix keeps a plugin from claiming the identity of the built-inLocalFileSink:horae undo --vaultrefuses a run applied throughfile-sink; without--vault,horae undogoes through the plugin host (#26, decision 37); - built-in fixture plugins.
fixture-source(fixture-source.serve, data and intents from a JSON fixture file, default the packaged one; afilemust be a regular file whose real path is inside apaths.readentry approved in the lock, opened withO_NONBLOCKand checked withfstat; its manifest asks for no path, and the walking skeleton's lock grants none, so only the packaged fixture is served there) andfile-sink(file-sink.write_note, built onLocalFileSink, so the same path and write rules) are stdio MCP servers inhorae.plugins.builtin, version 0.1.0. Their packaged manifests runpython3 -m <module>;horae.plugins.builtin.install(directory)writes them to<directory>/<name>/plugin.yaml(mode 0644, a temporary file thenos.replace, no symbolic link followed for the directories,InstallErrorwhensys.executableis empty) with the command pinned to the running interpreter, until M4 installs plugins into their own environments (#44, #46); - placeholder commit for built-ins. The walking skeleton's lock pins both plugins at
commit
0000000000000000000000000000000000000000(a commit of the core cannot name the commit that contains it). It is not fetched: the plugins ship inside the core. M4's fetch and verify (#44, #46) must special-case built-in plugins rather than try to resolve that commit; - live ports.
horae.runner.open_ports(instance, plugins_dir)builds theHostRegistry(HostRegistry.from_directory), opens aPluginHost(host_for_instance) andMcpSinksfor one run or one undo, and closes the host at the end of the block. Where plugins are installed is M4's;horae run,horae diffandhorae undoopen it on<instance>/plugins(#26, decision 37); - the walking skeleton (
examples/walking-skeleton) pins both plugins with the placeholder commit and a vault path to replace (in a copy of the directory);tests/test_e2e.pybuilds its lock from it at test time. The end-to-end test runs dry run (under the write guard, which then allows the plugins' processes and Horae's own state: the store,<state_dir>/locksand<state_dir>/plugin-runs; the vault is also compared byte for byte), run, replay and undo with real subprocesses, and fails when the module takes 60 s or more; - store first open (a flake fix found here).
Store.open(writable) initialises a database (create, WAL, migrate) under a POSIX advisory lock<db>.init.lock(0600,O_NOFOLLOW,flockretried with full-jitter backoff for at most the busy timeout, thenStoreBusy); an open whose database header already says WAL and the current schema version skips it. Read-only opens never take it nor create the file. The lock file is left in place (removing it would race with the next opener).
- sink operations by convention. An
Provisional decisions (#26, pending maintainer review)¶
- CLI commands: one exit-code table,
--jsoneverywhere,horae initandhorae run(#26). No contract changes. The rules (horae.cli,horae.cli_output,horae.cli_init,horae.cli_run,horae.cli_host,horae.cli_undo):- exit codes, the same for every command (
init,run,runs,diff,undo,replay,doctor; each command's--helplists the ones it uses,horae --helpthe table):0ok (no problem, listed, planned, identical, undone, created);1a configuration, store, plugin or runtime problem (doctor's problems, a run thatfailedor timed out or was lost, a sink failure,sink_mismatch);2usage error (a bad option, a missing argument, a malformed--var);3unknown or refused (an unknown run or pipeline, a refused run: failed, undone, already applied, a dry run, nothing to undo; a replay that cannot be compared; a non-emptyhorae inittarget);4different (a replay differs; a plan with problems, fromhorae difforhorae run --dry-run; an undo refused because a note changed);5locked (the pipeline is running,pipeline_locked; the apply lock is held,apply_locked: undo at once, a run afterAPPLY_LOCK_WAIT_S);70internal error (EX_SOFTWARE, only the exception's type is printed);130/143horae runinterrupted by SIGINT / SIGTERM (128 + the signal; aKeyboardInterruptreaching any other command is130, kindinterrupted). Changes from decisions 32 to 34:horae replayof an unknown run (or with no store) is3, not2;horae undorefused by a lock is5, not1. Decisions 27 and 31 (E) are unchanged; --jsonon every command: exactly one JSON document on stdout, ASCII, strict (horae.apply.render.dumps),schema_version: 1. An error is{"schema_version": 1, "error": {"kind", "message"}}, usage errors included (kindusage;JsonUsageCommandrecognises--jsonamong a command's arguments, before any--;JsonUsageGroupdoes the same for thehoraegroup's own errors,horae --jsonandhorae nope --json);horae replaykeeps its report with every key and outcomeerror, itserrorbeing the same{kind, message}object (nullwhen there is none; kindnot_comparablefor a replay that cannot compare), andhorae doctorits report (instanceis the resolved absolute path). AnOSErrorisstore_errorwhen it names the store's files, elseio_error(the file it names and itsstrerror, never the exception's text). Without--json, results go to stdout and errors to stderr as one line,horae <command>: <message>, with untrusted text escaped (safe: Unicode Cc, Cf, Zl and Zp except tab). No colour unless asked (horae diff --color). Common error kinds:config_invalid,plugins_invalid,store_error,unknown_run,unknown_pipeline,pipeline_locked,apply_locked,internal;horae init [DIR](default: the current directory) writes a working example instance, the walking skeleton:horae.yamlandpipelines/daily-fixture.yaml(the packagedhorae/init_template, kept identical toexamples/walking-skeletonby a test), a generatedhorae.lock(both built-in plugins at their version, the placeholder commit of decision 36, the permissions their manifests ask for, andfile-sink'spaths.writeset to the instance's ownvault/, an absolute path), an emptyvault/,state/(0700),plugins/(horae.plugins.builtin.install) and a.gitignorefor those three. It refuses (exit 3,target_not_emptyortarget_invalid) a target that is not a new or empty directory (a file, a symbolic link, anything inside it): no--force, nothing is ever overwritten (files are openedx). It is atomic: the lock is validated first (a path it cannot hold, a backslash for instance, istarget_invalid, exit 1, nothing written); the instance is built in a temporary directory, then a new target is onerenameof a hidden sibling (.horae-init-*), and an existing empty target (openedO_NOFOLLOW) gets the entries of a hidden directory built inside it renamed up into it (the directory itself is kept, so a shell inside it stays there, and its parent need not be writable); on any failure the temporary directory, the entries moved and the parentsinitcreated are removed.--jsonprints{schema_version, instance, vault, pipelines, plugins, files}. Instances are not relocatable in v1 (provisional):horae.lockholds the vault's absolute path and the installed manifests the absolute path of the interpreter;initsays so, andhorae doctorreports a copied or moved instance (below); Afterwardshorae doctorpasses andhorae run daily-fixturewritesvault/Daily/<date>.assistant.md;horae run <pipeline> [--dry-run] [--var KEY=VALUE]... [--json]: loads the instance (config_invalid), checks the pipeline (unknown_pipeline, 3) and the installed plugins (HostRegistry.from_directoryon<instance>/plugins:plugins_invalid, 1, before any process starts or any file is written), thenopen_portsandRunner.run(lock, recovery, execute, apply throughMcpSinks, whose identities the core prepares, decision 36).--varnames matchVarNameand may not be a built-in variable (now,timezone,date; usage, 2); at mostMAX_ITEMS - 1of them (the context holdsdatetoo; usage, 2), and a malformed one echoes only its name part (before=, truncated to 64 characters), never its value. A dry run records its run and prints the change set it would apply (plan_changes, rendered likehorae diff, without a second header line; with problems, exit 4; when a sink plugin could not start,plugin_unavailable,spawn_failed,startup_timeoutorhandshake_failed, exit 1, kindplugin_unavailable: a problem, not a difference). The run's status gives the code:ok,noop,degraded0;failed1 (run_failed;apply_locked5);RunTimedOut1 (timeout),RunLost1 (run_lost),PipelineLocked5.--jsonprints{schema_version, run_id, run: {id, pipeline, status, dry_run, started_at, finished_at, intents, changes: [{intent, target}], cost, violations, error_kinds, error}, plan, error}(run_idas soon as the run's row exists, fromRunner.run(on_begin=), also when no record was saved;runisnullwhen none was,planwithout--dry-run);error_kindsare the failed steps' kinds (also appended to the text error). No LLM backend in M1: a pipeline with anllmstep fails withllm_unavailable(exit 1); M2 wires the backends intoopen_ports(llm=...). Signals (follow-up of decision 31 F): SIGINT and SIGTERM handlers (loop.add_signal_handler, removed afterwards) cancel the run's task and the command exits 130 / 143, naming the run. During the engine phase the runner saves the partial record (failed, kindcancelled), which is printed. The apply phase is shielded (provisional): once it has started planning, a cancellation is remembered, the apply finishes (each sink call bounded bycall_timeout_s), the record is saved with its real status (its changes were applied:ok, say) and only then is the run reported interrupted; a cancellation while it waits for the apply lock stops the wait (failed, "cancelled before apply", nothing applied). If the run is nonetheless abandoned during the apply (a crash), its error says "run crashed during apply (); run horae undo <id>to revert what was written", the command prints "abandoned during apply; runhorae undo <id>" and--jsonhas the id; a cancellation that abandons a run sayscancelled: ..., neverrun crashed (CancelledError). A second signal while the run stops is ignored: the runner's grace period (STOP_GRACE_S) still bounds the stop, after which the run is abandoned as before. Secrets: the run's error and messages come from the record and the host, which redact them; internal errors print the exception type only;- sinks for
horae diffandhorae undo: through the plugin host (open_ports,McpSinks) when the instance has aplugins/directory, so a run applied byfile-sinkis planned and undone byfile-sink(decision 36's identity).--vaultstays as an explicit override: the built-inLocalSink(diff, read only) orLocalFileSink(undo) on that directory, for instances without plugins or runs applied by the built-in sink; undo through it refuses a run applied by a plugin (sink_mismatch). Without plugins and without--vault, the built-in sinks have no vault (vault_unset), as before.horae diffthrough the host starts the plugins, which only read (<ns>.read); the store is still opened read-only; - where plugins are installed:
<instance>/plugins/<name>/plugin.yaml(horae.cli_host.PLUGINS_DIR), until M4'shorae plugin add(#44) decides otherwise; horae doctorchecks, beyond the configuration (check_instance,horae.cli_host.instance_problems): everypaths.read/paths.writeentry ofhorae.lockexists; an instance with its ownvault/that the lock does not write to is a problem (a copied instance still writing to the original's vault); with aplugins/directory, the plugins match the lock (check_plugins) and each stdio command (its pinned interpreter) exists and is executable (resolve_command). Each is a problem (exit 1) naminghorae.lockor the plugin's manifest;- follow-ups (out of scope here): enforcing the manifests'
horaeversion range againsthorae.__version__; whether a second identical run should benooprather thanok.
- exit codes, the same for every command (
Provisional decisions (#28, pending maintainer review)¶
- LLM backend interface, the
anthropicbackend, usage and cost (#28). Compatible v1 additions and the rules ofhorae.llm(interface) andhorae.llm.backends.anthropic(SDKanthropic1.17 overhttpx2, Messages API,anthropic-version: 2023-06-01):- contract changes (all optional):
models.<alias>.priceinhorae.yaml,{input_per_mtok, output_per_mtok, cache_read_per_mtok?, cache_write_per_mtok?}, US dollars per million tokens, each0to10000;models.<alias>.max_output_tokens(1to1000000), a cap on every call'smax_tokens;base_urlof abackend: anthropicalias must behttps://(C).Usage(run records:llm[].usage,cost) gainscache_read_tokens,cache_write_tokens(when the provider reports them;tokens_instays the input billed at the full price) andpriced(falsewhen the alias has noprice:usdis then0). Without a cache price, cache reads are priced as input tokens and cache writes at twice the input price (conservative). Apriceis part of themodelssection, so changing it changesconfig_digest(decision 33), not the LLM cache key. Thehorae doctorreport'sseveritymay now bewarning(decision 27): a warning is printed and listed but does not fail the check (okstaystrue, exit0); - A. no shipped price list: prices change and differ per account, so the instance
states the ones it pays. Without one, only
tokens_outbounds the step, sohorae doctorwarns about each cloud (anthropic) alias used by anllmstep that has noprice; - B. pre-flight budget:
ModelBackends.renderrefuses the attempt withbudget_exceeded, before any request (and before the key is read), when the remainingtokens_out(capped bymax_output_tokens) is below 1, or, with a price, when the input alone may cost more than the remainingusdor what is left buys no output token. The input is bounded without acount_tokenscall: a token is at least one UTF-8 byte, so the canonical JSON size of the whole rendered payload (system, messages, schema) plus a margin of 512 tokens (INPUT_TOKEN_MARGIN, for the framing and structured-output instructions the provider adds) is the bound;max_tokensis then what the remainingusdbuys after that bound. The engine still checks the reported spend after the call; - C. explicit network path: the core LLM client ignores the ambient environment: no
HTTP(S)_PROXY/ALL_PROXY, no.netrc, noSSL_CERT_FILE/SSL_CERT_DIR(an explicithttpx2.AsyncHTTPTransport(trust_env=False, verify=True)and a client withtrust_env=False;verify=Truewithouttrust_envishttpcore2's default context on the system trust store, which reads noSSL_CERT_*, whereasssl.create_default_context()would, through OpenSSL's default verify paths). Redirects are not followed; OpenTelemetry spans are off. An explicit proxy or CA option (models.<alias>.proxy/ca_file) is a later decision; - D. intents: raw intents live in a reserved top-level
intentsproperty of the skill's output object.ModelBackendsvalidates the whole output, then, only whenintentsis present, requires a list (elseoutput_invalid, with the usage), moves it intoLlmResponse.intentsand removes it fromoutput. #27 (skill format) reserves the name in skill output schemas; #31 validates against the schema including it; #35 routes the intents; - E. what is recorded:
LlmCall.requestis a summary, not the payload:backend,model,max_tokens,body_sha256/body_bytes(the exact bytes sent), and the SHA-256 and size of the skill prompt (system_*), the canonical input (input_*) and the output schema (schema_*), withrepair_errors(how many errors were sent). The input is already in the run's data andLlmCall.input_hash; the full body is never recorded, dry runs included (they make no LLM call); - G. the #31 validator is mandatory before production use: structured outputs drop
the constraints they do not support (
anthropic.transform_schemamoves them into descriptions), so withoutModelBackends(validate=...)an output may breakmaxLength,pattern, numeric bounds and the like; - two layers:
ModelBackendsis the engine'sLlmBackend(alias → backend, model,base_url,secret,price; prompt from aPromptSource;max_tokensfrom the budget); aProviderBackendper alias makes one request with no tools. Both split an attempt intorender(pure: the exact provider payload, aRenderedRequestwhosebody()is canonical JSON bytes frozen at render time; no I/O, no secret) andsend(one network call with a fresh copy of exactly those bytes; a payload changed after rendering is refused withinvalid_request), so the core can inspect what leaves the host first (T10, #34/#53);completeissend(render(...)); - the API key comes from the declared secret only (
models.<alias>.secret, through the instance'sSecretResolver, decision 25), resolved on the first call. The SDK readsANTHROPIC_API_KEY,ANTHROPIC_AUTH_TOKEN, credential profiles andANTHROPIC_BASE_URLonly when it is not given a key and a URL, so it always gets a placeholder key and an explicitbase_url(defaulthttps://api.anthropic.com). SDK retries are disabled (max_retries=0): the engine owns the single repair retry; - headers are rebuilt: the SDK merges
ANTHROPIC_CUSTOM_HEADERSfrom the environment into every request, which can override any header. A request hook on its HTTP client refuses any request butPOST <base_url>/v1/messagesto the alias' origin and replaces every header with exactlyhost(from the request URL),acceptandcontent-type(application/json),content-length(the body's length),anthropic-version(2023-06-01),user-agent(horae) andx-api-key(the declared secret, set at the last moment). NoAuthorization,anthropic-beta,x-stainless-*(platform, retry or timeout) oraccept-encodingheader is sent. A refusal carries its reason in its own exception (no shared state); - logging: at
DEBUG(ANTHROPIC_LOG=debugor a logging configuration) the SDK logs request options, the prompt and the input included. Building a client pins theanthropic,httpx2andhttpcore2loggers, and their children that set a lower level, toWARNING; - request shape:
systemis Horae's preamble (the user message is untrusted data, never instructions; answer with JSON matching the schema), then the skill's rendered prompt. One user message holds the input as JSON inside<input>tags, then, on the repair retry, the previous attempt's schema errors as a JSON array inside<schema_errors>tags (framed as data, not instructions). In both, every<is written as the JSON escape<(valid JSON, since<only occurs inside strings), so the data cannot close its tag. The output is constrained with structured outputs (output_config.format: {type: json_schema, schema}, the schema passed throughanthropic.transform_schema); the text must parse as one JSON value: noNaNor infinite number (1e999), no duplicate key, no nesting beyond the parser's limit; - error kinds (messages are Horae's: the HTTP status and the API error
type, never the API's text; raised outside the SDK's exception handler, so neither__cause__nor__context__reaches the SDK error and its request):timeout(SDK timeout, 408, 504),rate_limited(429),auth_failed(401, 403, an unresolvable secret),overloaded(529, 503),invalid_request(400, 404, 409, 413, 422, an unknown alias, a schema structured outputs cannot take, a payload changed after rendering),output_invalid(refusal,max_tokensor context-window truncation, tool or other non-text content, unacceptable JSON,intentsnot a list),host_error(connection failure, a refused request, another status);budget_exceeded(B),backend_unavailable(an alias whose backend has no implementation yet) andskill_unavailable(no prompt for the skill) come fromModelBackends. Every rejection after a successful HTTP response carries the usage the response reported; when it reported none usable, the call is charged conservatively (the input bound and the wholemax_tokens); - wiring:
open_portsgives the runner aModelBackendsover the instance's aliases when a pipeline has anllmstep (sharing the host'sSecretResolver; lazy; closed with the ports), sohorae runno longer fails withllm_unavailable(decision 37) when an alias is configured.horae doctorreports a model alias used by anllmstep whose backend is not available (models.<alias>.backend), besides its secret; - integration points (#27): the prompt, viewed input, output schema and skill version
come from the
LlmRequest(RequestPromptsreads the fields #27 added:prompt,output_schema,skill_version). A request without a prompt or schema (an engine given noSkillSource) stops withskill_unavailablebefore any request;skill_unavailablemeans "no usable prompt for this skill here", and #27'sskill_invalid(a skill that is present but malformed) is reported while planning, before the LLM layer is reached.open_ports(horae.runner._ports) builds both the ownedModelBackendsand theDirectorySkillssource (Ports.skills, decision 39); the reservedintentsproperty is the one #27's schema check requires of a skill that declares intents (horae.skills.INTENTS_PROPERTYisINTENTS_KEY).
- contract changes (all optional):
Provisional decisions (#27, pending maintainer review)¶
- Skill format and loader (#27). A new contract,
schemas/skill/v1.json(horae.contracts.skill.SkillManifest), the loaderhorae.skills, and one optional run-record field,llm[].skill_digest(a compatible addition). Numbered 39 because #28 (decision 38) merges first. Choices to verify:- (A) layout. A skill
<namespace>/<skill>is the folderskills/<namespace>/<skill>/of the plugin that lists it inprovides.skills(HostRegistry.plugin_for_skill, then the plugin's installed directory). The namespace is a folder level so one plugin can ship skills of two namespaces without a clash. The folder holdsskill.yaml, the prompt (prompt.mdby default) and the output schema (output.schema.jsonby default); other files are ignored; - (B)
skill.yamland race-safe reads:name(must equal the skill ref),version(semver),description(one line),input_view(1 to 256 paths), optionalpromptandoutput_schemafile names, optionalintents. File names are one path segment (^[A-Za-z0-9_][A-Za-z0-9_.-]*$), so../, absolute paths and hidden files cannot be written. The loader opens the plugin root and walksskills, the namespace and the skill one component at a time relative to the previous descriptor (dir_fd), eachO_DIRECTORY | O_NOFOLLOW, then opens each file relative to the skill folder withO_NOFOLLOW | O_NONBLOCKand checks it withfstat: a regular file with exactly one hard link. Every symbolic link inside the skill tree is refused (a symlinked skill folder, namespace orskillsfolder too, and a link between two files of the folder), and so is a hard link to a file elsewhere. Swapping a component for a link between a check and the read cannot redirect the read. Sizes:skill.yaml, prompt and schema at most 64 KiB each. Every problem, including a non-finite number, a lone surrogate, a$refchain or a recursion too deep, is aSkillError(skill_invalid); - (C) input view: dotted paths with
[], not JSON Pointer:tasks[].title,[].data(acollectoutput is an array at the root),matrix[][].v. JSON Pointer names one location (/tasks/0/title) and has no "every element", and its~0/~1escapes are hard to review in YAML. Names are[A-Za-z_][A-Za-z0-9_-]*: a key with another character cannot be selected in v1; the bracket-quoted form (["a.b"]) is reserved for it. A path selects the whole value it ends on; overlapping or shape-contradicting paths are refused.input_viewis a list of paths or a mappingpath: {options}(for #34's field classes,events[].attendees[]: {class: person}): options are free-form but bounded (at most 16 per path, names like the paths', values booleans, finite numbers, one-line strings or lists of at most 64 of them);class, when given, is one ofperson,email,phone,place,amount,free_text. v1 does not act on options; they join the skill's digest only when present, so a mapping without options has the list form's digest. Applying the view (InputView.apply) keeps exactly the declared keys that are present, maps[]over arrays (keeping order, dropping elements of the wrong shape) and re-encodes the result withsort_keys, so object keys are sorted at every depth (inside selected whole values too) and nothing is shared with the input; a value of the wrong shape selects nothing (the root:null, see G). Missing fields are not an error: the input is untrusted data; - (D) prompt: no template syntax in v1. The prompt is sent verbatim;
{{and}}are refused so a later syntax (e.g.{{date}}from the run context, never from the input) is a compatible addition. It must be non-empty UTF-8 without a character of the Unicode categoriesCc,Cf,Co,Cs,Cn,Zl,Zp(but tab and newline: no CR, so the digest does not depend on line endings), which covers the bidirectional controls, zero-width characters, U+00AD, U+180E, the tag characters U+E0000 to U+E007F and U+2028 / U+2029, nor another invisible character (the variation selectors U+FE00 to U+FE0F and U+E0100 to U+E01EF, the combining grapheme joiner, the Hangul fillers). The input is never interpolated into the prompt: it travels separately, as data (tenet 5); - (E) output schema: draft 2020-12, self-contained, regex-free and bounded
(
horae.skills.check_output_schema): the metaschema, an optional$schemathat must be 2020-12, a root"type": "object", only local$refs (at most 32 chained, no cycle, no%: the validator percent-decodes pointers; resolved withreferencing, as the validator resolves them), every$defs/definitionsentry bounded even when unreferenced, and no$id,$anchor,$dynamic*,$recursive*or$vocabulary; nopattern,patternProperties,propertyNamesor"format": "regex"(a plugin author's regex is a ReDoS risk; #31 must still validate outputs in a worker it can kill on a timeout); every subschema a value meets has atype,enum,const,$refor combinator; astringneedsmaxLength, anarraymaxItems(anditemspast itsprefixItems), anobjectadditionalProperties: false(as the backends' strict structured-output modes require), anintegerornumbera finite lower and upper bound. The size bound is in UTF-8 bytes of the compact JSON (separators=(",", ":"),ensure_ascii=False) and is a sound worst case: a string counts6 * maxLength + 2(every code point escaped as\uXXXX), a number the digits of its larger extreme (anintegertwo more, for3.0; anumberor an extreme of 10^15 or more at least 25, the longest floatrepr),enum/consttheir longest serialisation (1may be1.0);anyOf/oneOftake the largest branch,allOfthe smallest bounded branch (unconstrained branches are skipped; refused only if none is bounded), and a keyword that does not bound is skipped when another one does. #31 re-serialises the validated output in that form, so the bound holds for what it stores. A property test (hypothesis, a new dev dependency) checks it on random bounded schemas. The bound must be at mostMAX_OUTPUT_BYTES(256 KiB); the file nests at most 64 levels and is strict JSON (no duplicate keys, noNaN, no number overflowing to infinity). Amended by #31 (decision 44 G): the product ofanyOf/oneOfbranch counts along any path of the schema,$refs followed (memoised per$ref), is at mostMAX_COMBINATOR_FANOUT= 1024 (a validator tries every branch, so nested alternatives, through a chain of$defssay, make one validation exponential); alternatives side by side (properties,allOf) do not multiply. This addsjsonschemaas a runtime dependency (it was a dev dependency; #31 needs it to validate outputs). Amended by #36 (decision 48 D4): anenumor aconstneeds atypebeside it (SchemaProblemnaming the JSON pointer: Anthropic's structured output,transform_schema, refuses one without), andhorae doctorreports a loaded skill's schema that a backend's structured output still refuses (schema_problems, with the pointer of the deepest refused subschema): an error when an alias of that backend runs the skill, else a warning; - (F) intents.
intentsis a list of types or a mappingtype: max(1 to 256, #35): at mostmaxintents of that type perllmstep; more is aguardviolation that degrades the step (decision 46; it wasintent_rejectedbefore #35); a reused output over the limit is a cache miss. Omitted or empty: the skill proposes none. They must be within the plugin's approvedpermissions.intents(load error otherwise). The engine checks the LLM's intents against the plugin's permissions narrowed to the skill's, on fresh and reused outputs alike, and atask.update_statusfingerprint must appear in the viewed input (what the model was shown), not merely in the data collected. The reserved output property (#28): the LLM proposes intents in a top-levelintentsproperty of its output, which the backends extract; a skill that declares intents must declareproperties.intentsas a bounded"type": "array"in its output schema, and a skill that declares none may not; - (G) the engine (
execute(..., skills=SkillSource),Ports.skills, built byopen_portsasDirectorySkillsover<instance>/plugins): the skill is loaded while planning, before the backend is checked, so an invalid skill fails the run before any plugin is called (skill_invalidon thellmstep, even without a backend; a port bug ishost_error), andhorae doctorloads every skill anllmstep uses (aSkillErroris a problem).LoadedSkillexposesname,version,digest,prompt,output_schema(a fresh deep copy on each access: the skill keeps canonical bytes),intents,intent_limits,output_bound,view_pathsandview(data).LlmRequestgainsprompt,output_schema(a fresh copy per attempt),skill_versionandskill_digest, and itsinputis the viewed input, so a backend (#28) only sends it. A viewed input ofnull(the input does not have the view's shape) degrades the step without calling the LLM (input_invalid).LlmCall.skill_versionis the loaded skill's version (not the backend's),LlmCall.skill_digestits digest, andLlmCall.input_hashthe hash of the viewed input. Without a skill source (fakes, older callers) nothing changes; whether a real backend must refuse a request without a prompt is a question for the maintainer; - (H) cache key. With a skill, the key (
RunRecord.input_hash) is the SHA-256 of{skill, plugin: {name, version, commit}, model, input: <viewed input>, skill_version, skill_digest}, whereskill_digestis the SHA-256 of the canonical JSON of{name, version, prompt, output_schema, input_view, intents}(plusview_optionsandintent_limitswhen the manifest has any; notdescription). A new version, an edited prompt, schema, view or intents is a cache miss; a change to an undeclared input field is not (the model would see the same thing). Skills are loaded once per run (DirectorySkillscaches them), so a run sees one version of the files; - (I) replay.
replay(..., skills=)passes the source to the engine;horae replayreads skills from<instance>/pluginswhen it exists (local files only, likeLockRegistry). A skill edited since the run replays as different, by design; when both records carryllm[].skill_digest, the report adds the note "skillchanged since the run" and an llm.<skill>.skill_digestsummary field.
- (A) layout. A skill
Provisional decisions (#30, pending maintainer review)¶
- The
openai-compatibleandollamabackends (#30). Two compatible v1 additions and the rules ofhorae.llm.backends.openai_compatibleandhorae.llm.backends.ollama, which keep every rule of decision 38 (render/send, the key only from the declared secret, rebuilt headers, the explicit network path, quiet loggers, strict JSON, the pre-flight budget, clean error chains, the summary recorded asLlmCall.request, reservedintents) and share its code (horae.llm.backends._shared):- contract change (optional):
models.<alias>.structured_output,json_schema(the default when unset),json_objectornone, accepted forbackend: openai-compatibleonly (the model and the JSON Schema both refuse it on another backend). It is the fallback for a server that lacks JSON Schema structured output; - contract change (optional):
models.<alias>.max_tokens_field,max_tokens(the default when unset) ormax_completion_tokens,openai-compatibleonly (refused on another backend by the model and the JSON Schema), for OpenAI's reasoning models, which refusemax_tokens. There the limit also bounds the hidden reasoning tokens, so a lowtokens_outcan end inlengthwith no visible output (anoutput_invalidtruncation, charged); the payload keys follow the field, so a payload rendered for one field is refused by an alias set to the other; - A. no SDK: both talk to their API with a direct
httpx2client (one JSONPOST). TheopenaiSDK would add a dependency and what theanthropicbackend has to neutralise (OPENAI_API_KEY,OPENAI_BASE_URL,OPENAI_ORG_ID/OPENAI_PROJECT_ID, its own retries, platform headers and debug logging); theollamaclient readsOLLAMA_HOST. Nothing here reads the environment. The posted bytes are the canonical JSON of the rendered payload, so they equalRenderedRequest.body()byte for byte; - B. what
base_urlmeans: foropenai-compatibleit is the API root with its version prefix, as the OpenAI SDKs take it (https://openrouter.ai/api/v1,https://api.mistral.ai/v1,http://vllm:8000/v1), and the only request isPOST <base_url>/chat/completions; forollamait is the server root (http://ollama:11434) and the only request isPOST <base_url>/api/chat. A request to any other origin, path or query is refused (host_error).http://follows decision 24 (loopback, private and single-label hosts only); - C. the key is optional:
secretis optional for both; when declared it is sent asAuthorization: Bearer <key>(forollama, to a proxy in front of it), else noAuthorizationheader is sent. The headers are exactlyhost,accept,content-type,content-length,accept-encoding: identity,user-agent: horaeand that one (anthropicsendsaccept-encoding: identitytoo); - D.
openai-compatiblerequest:model,max_tokens,stream: falseand two messages (system: the preamble, then the skill's prompt;user: the tagged input and schema errors of decision 38).json_schemasendsresponse_format: {type: json_schema, json_schema: {name: horae_output, schema, strict: false}}:strict: falsebecause OpenAI's strict mode refuses schemas that do not mark every property required or that use keywords it lacks (maxLength,pattern), and the #31 validator checks the full schema anyway (decision 38 G).json_objectsends{type: json_object}andnonenoresponse_format; both append the schema to the system prompt. Withjson_schemathe schema is not also put in the prompt: it is inresponse_format, and repeating it would make the request larger and give the model two copies to reconcile; the trade-off is that a server which silently ignoresresponse_formatgets no schema text (the #31 validator still refuses its output; such a server should usejson_objectornone).strict: falseis recorded here as the decision (see above).max_tokensby default (what the compatible servers take;max_tokens_fieldabove for reasoning models). OpenRouter'sproviderrouting fields (order,allow_fallbacks,data_collection...) are not sent and cannot be configured: a later per-alias option, since routing decides which company sees the data; - E.
openai-compatibleresponse: exactly one choice,finish_reason: stop, andmessage.contentone JSON value.length/model_length(truncation), a non-emptymessage.refusalorcontent_filter(refusal),tool_calls/function_calland any other finish reason areoutput_invalidwith the usage. Usage isprompt_tokens/completion_tokens; a reportedprompt_tokens_details.cached_tokens(at mostprompt_tokens) becomescache_read_tokensand is taken out oftokens_in. An error status carries the API's errortypewhen it is a short identifier; - F.
ollamarequest and response:model,stream: false,format(the output schema: Ollama's structured outputs, Ollama 0.5 or later),options.num_predict(themax_tokens) and the same two messages.donemust betrue;done_reason: lengthis a truncation, tool calls and any reason butstop(or none, as older servers send) areoutput_invalid. Usage isprompt_eval_count/eval_count; Ollama may omitprompt_eval_countfor a cached prompt, and a missing count is charged conservatively (decision 38). Ollama'serrortext is never shown: the message has the status only (a missing model is HTTP 404,invalid_request); - G. cost and
horae doctor: without apricea call costsusd: 0(priced: false), as for every backend.horae doctortreatsollamaas local (no price warning) andopenai-compatibleas cloud (the warning of decision 38 A, which never fails the check), even when itsbase_urlis a local vLLM: the backend name is the only signal kept simple here. The #34 design note proposes an explicitlocal:flag per alias; when it lands it replaces this rule; - H. shared conformance suite:
tests/test_llm_backends_shared.pyruns the same tests overanthropic,openai-compatibleandollamawith recorded synthetic responses (tests/fixtures/llm/<backend>/: success, truncation, refusal where the API has one, tool call, 401, 429, 5xx, malformed JSON, missing usage); a new backend joins it by adding aKindintests/llm_backend_kinds.py; - I. the response is bounded (every backend,
anthropicincluded, through_shared.BoundedTransportaround the client's transport):accept-encoding: identityis sent; the cap of a call isresponse_cap(max_tokens) = min(8 MiB, max(1 MiB, 64 × max_tokens))bytes of decoded body (64 bytes a token: a token is a few bytes of text, which JSON may escape up to 6 bytes a character, inside the provider's envelope). A success whosecontent-lengthexceeds it is refused before its body is read; one that grows past it while read (chunked) is refused at the cap. A server that compresses anyway is inflated by Horae (gzip,deflate), at most one byte past the cap per step, so a gzip bomb (305 KB inflating to 300 MiB) is refused with about one cap in memory; any othercontent-encoding(or a list of them) and corrupt compressed data are refused. All of these areoutput_invalidwith the conservative usage (decision 38: the input bound and the wholemax_tokens), since the provider may have billed the call. An error body is cut at 64 KiB (its status still maps the error); - J. the body is read strictly: decoded as UTF-8 only (
bytes.decode("utf-8"), no charset sniffing: UTF-16, a stray0xffor an encoded surrogate are refused), then parsed by the strict JSON parser of decision 38; it must be one JSON object.anthropicnow reads the raw response itself the same way (the SDK posts the canonical bytes withcast_to=httpx2.Responseand still maps HTTP and connection errors; no SDK model is built from the response). Any exception other than anLlmErrorwhile reading the result isoutput_invalidwith the conservative usage, never a crash. An error body that is not UTF-8 gives the status only; - K. reported usage is untrusted: a token count must be an integer from 0 to
10**12(10**400or10**308, which would overflow the cost to infinity, are unusable: the call is charged conservatively). A usable report is then floored:tokens_in(with the cache tokens) at leastceil(request bytes / 4)andtokens_outat leastceil(UTF-8 bytes of the output text / 4), the latter capped atmax_tokens(what a provider honouring the request may bill). The larger value is the one recorded, priced and charged to the budget; the reported value is not kept separately (kept simple: oneUsage). A server that reports0 / 0is still charged for what it plainly sent; - L.
http://is checked at connect time (decision 24 limits the host name; this limits where it resolves): for anhttp://base_urlthe transport's network backend (_shared.LanOnlyNetwork) resolves the host when it opens a connection and refuses unless every address is loopback (127/8,::1), RFC 1918 (10/8,172.16/12,192.168/16) or IPv6 ULA (fc00::/7), an IPv4-mapped address being checked as IPv4; link-local (169.254/16,fe80::/10, where cloud metadata services answer) and CGNAT (100.64/10) are refused. It then connects to the checked address itself, so a second lookup cannot rebind the name. A refusal ishost_error("request refused: an http endpoint that resolves to a public address"), like every other refused request, and nothing is sent; a failed lookup is a connection error (host_error, ortimeoutwithin the step's timeout).https://endpoints are not restricted (TLS authenticates the host); - M.
horae doctorwarns about a key overhttp://: an alias used by a pipeline with asecretand anhttp://base_urlgets a warning (never a failure): the key crosses the local network in clear, readable by anyone on the path; - N. the
base_urlpath cannot traverse: besides decision 24, abase_urlwhose path has a.or..segment or an encoded/,.or\(%2F,%2E,%5C, any case) is refused, since a server or proxy may decode it into a path the guard never compared (https://h/%2e%2e/v1,https://h/a%2Fb,https://h/v1/../x).
- contract change (optional):
Provisional decisions (#33, pending maintainer review)¶
- Budgets per day and the usage ledger (#33). (39 and 40 are taken by #27 and #30.)
A compatible v1 addition and the rules of
horae.runner._budget, the store andhorae usage:- contract change (optional):
horae.yamlbudgets: {daily?, pipelines?}, wheredailyis{usd?, tokens_out?}(at least one, and notnull: eachanyOfbranch of the JSON Schema requires its property as a number;usd > 0,tokens_out >= 1) for every pipeline together, andpipelines.<name>.dailythe same for one pipeline (a name that is not a pipeline of the instance is a loader problem). Both apply; the lower allowance wins. The day is the instance'stimezoneday (not a trigger's).usdbounds only priced aliases (an alias withoutpricerecordsusd: 0, decision 38 A);tokens_outbounds every call. The step's ownbudgetis unchanged and still bounds both attempts together; - reservation: before every LLM attempt, the runner first prepares the request
outside any lock (
ModelBackends.prepare: the alias, the skill's prompt from thePromptSource, which may read files, the provider backend and the input bound); then, in one store transaction (BEGIN IMMEDIATE, so the processes of other runs wait for it), it reads the day's spend from the ledger (settled calls at their cost, unsettled ones at their reservation), caps the attempt's budget with what is left of each ceiling (see A for a refusal), renders the request with that budget (ModelBackends.render(capped, prepared): pure sizing and payload, no I/O; its pre-flight of decision 38 B may refuse it too) and reserves the most it can cost (ModelBackends.worst_case: the input bound at the input price, or at the cache write price for a provider backend thatmay_write_cache, plusmax_tokensat the output price: the boundmax_tokensalready keeps within the budget). Amended by #113 (decision 42's amendment (#113, live run)): the output part isoutput_attempts × max_tokensat the output price (a backend that may bill several outputs for one call,claude-cli: 4; 1 for the others), andmax_tokensdivides the step's remainingtokens_outandusdbyoutput_attemptsso it still fits. AnotherLlmBackend(a test fake) reserves the capped budget itself. Two runs of different pipelines therefore never both spend the last of a ceiling (tests/test_budgets.pyhas a two-process test whoseday_spendwaits between the read and the reservation: it fails with a deferred transaction). Not the apply lock: an LLM call can take minutes and must not block other runs' applies; - settling, right after the call (not with the step record: failed attempts cost
money too and have no
LlmCall): the reported usage (also of a failed call,LlmError.usage; zero for a backend's cached response; a cost above the reservation is logged, amounts only, and the row markedover_reservation); a refusal that reports no usage and means the provider processed nothing (budget_exceeded,backend_unavailable,skill_unavailable,invalid_request,auth_failed,rate_limited,overloaded) releases the reservation; any other failure without usage (a timeout, a lost connection, a cancellation) keeps the reservation as anestimatedcost. Crash consistency: a process that dies between reserving and settling leaves itsreservedrow, which keeps counting for its day: a crash can over-count, never under-count (until the run is abandoned or recovered, see D). A store failure while reserving refuses the call (host_error); while settling it is logged (type only) and the reservation stays; - the ledger is the
llm_usagetable (migration 4): per attemptrun_id,pipeline,step,attempt,alias,backend,model,state(reservedorsettled), tokens in and out, cache read and write tokens,usd,priced,estimated,over_reservation,at(UTC) andday(local). The ledger outlives its runs (C); horae usage [--pipeline P] [--since DATE] [--until DATE] [--by day|pipeline|model] [--json]groups the ledger by day and pipeline (or by day, pipeline, or backend and model), oldest first, with aTOTALrow; dates are local days, inclusive. Cells of calls of an unpriced alias are flagged*, calls in flight+, calls settled at their reservation~and calls that cost more than reserved!, with a footnote each; a cost under a ten-thousandth of a dollar shows as<$0.0001.--by modelgroups by backend, model and alias: a call that reached no provider has anullbackend and model (-in the table). The store is opened read-only (decision 31 E: a missing store lists nothing, an older schema exits 1). Exit codes as decision 37:0listed,1configuration or store problem,2usage error (a malformed date,--sinceafter--until, an unknown--by),70internal.--jsonprints{schema_version: 1, instance, by, pipeline, since, until, rows: [{<by keys>, calls, tokens_in, tokens_out, cache_read_tokens, cache_write_tokens, usd, unpriced_calls, in_flight_calls, estimated_calls, over_reservation_calls}], total};- (A) a minimum useful output: a call is refused (
budget_exceeded, no request, nothing reserved) when what a daily ceiling leaves cannot buyMIN_OUTPUT_TOKENS = 256output tokens, or fewer when the step's own budget buys fewer (min(256, what the step alone allows)): an answer cut short is worse than none. The refusal names the daily ceiling (the instance daily budget leaves ...), also when the pre-flight of decision 38 B refuses only because of it; a step whose own budget is too small is refused in the step's own words, as before; - (B)
horae doctorwarns when ausdceiling (budgets.dailyorbudgets.pipelines.<name>) covers a pipeline whosellmalias has noprice: its dollars are then unbounded, onlytokens_outbounds it; - (C) the ledger lives independently of runs:
run_idis nullable,ON DELETE SET NULL, soprune_runsnever changes a day's totals; the ledger's own retention isStore.prune_usage(older_than)(settled rows of earlier local days; reserved rows are kept); - (D) abandon and recovery:
abandon_run(the stale-run recovery calls it too, a compare-and-set on the run's status) turns the run'sreservedrows intosettledones at their reservation,estimated = 1;horae usagetells calls in flight (+,in_flight_calls) from settled estimates (~,estimated_calls); - (E) dry runs are charged: they call the model. PLAN.md's "a dry run writes nothing" is about user data (decision 32 D5): Horae's own state, the run record and the usage ledger, is written;
- (F) the day is stored at reservation time: a later
timezonechange does not rewrite history (past rows keep their day); local midnight and DST transitions follow the instance's time zone (a 23- or 25-hour day is one day); - provider prompt caches: a
ProviderBackenddeclaresmay_write_cache(defaultFalse;anthropicisFalse, since Horae sends nocache_control;claude-cliisTrue, decision 42). For such a backend the input bound is priced at the cache write price (cache_write_per_mtok, else twice the input price) in bothmax_tokensandworst_case, so a settled call never exceeds its reservation; a backend without it that reports cache writes beyond the bound is flaggedover_reservation(and logged). Likewise aProviderBackenddeclaresoutput_attempts(default 1;claude-cliis 4, #113):worst_casereserves that many outputs ofmax_tokensandmax_tokensdivides the step's budget by it; an unusable declared value (not anintof at least 1, or abool) isbackend_unavailable, a larger one is clamped toMAX_OUTPUT_ATTEMPTS(16); - untrusted usage (decision 40 K): a backend's floored usage (input at least a
quarter of the request bytes, output at least a quarter of the output bytes but at
most
max_tokens) and its conservative charge (input_boundof the payload sent plus the wholemax_tokens) stay within the reservation:ModelBackends.preparesizes the input bound on the payload at the largestmax_tokensthe request allows (itstokens_out, capped by the alias'max_output_tokens), so the payload actually sent, with amax_tokensno larger, is never bigger. A count a provider reports above the bound but under10**12is kept (decision 40) and flaggedover_reservation; - follow-ups: a monthly ceiling; provider-side spend limits (#63); calling
prune_usagefrom a retention setting.
- contract change (optional):
Provisional decisions (#29, pending maintainer review)¶
- The
claude-clibackend with isolation (#29, the design note on #97; every recommendation accepted). One compatible v1 addition and the rules ofhorae.llm.backends.claude_cli. Not a legal assessment: personal headless use ofclaude -pon your own plan is PLAN.md's ⚠️ unverified reading (risk #70); this backend is "personal use under your plan's terms", andanthropicwith an API key stays the recommended backend for published setups (ADR 0005).- contract change (optional):
models.<alias>.command, an absolute path (no control characters, at most 1024 characters), accepted forbackend: claude-clionly (the model and the JSON Schema both refuse it on another backend). Unset,claudeis looked up on the fixed childPATH(/usr/local/bin:/usr/bin:/bin), never Horae's ownPATH(answer 6). The native installer putsclaudein~/.local/bin, which is not on it: such setups setcommand.commandmust name the native binary: the npm package'sclaudeis a#!/usr/bin/env nodescript, andnodeis usually not on the fixedPATH, so its--versionfails; the error then says so (finding 9). Symlinks are resolved when the backend first runs it, so one run uses one release; - token mode only (answer 1): the alias'
secret(aCLAUDE_CODE_OAUTH_TOKENmade withclaude setup-token) is passed asCLAUDE_CODE_OAUTH_TOKEN, revealed into the child's mapping only. The contract keepssecretoptional (a login mode may come later), but an alias without it is refused at the first call (backend_unavailable, nothing runs) and byhorae doctor(an error). A secret that cannot be resolved, or holds a NUL, isauth_failed. Checked locally on 2.1.284: with an emptyHOMEand no token the CLI answers "Not logged in" (no ambient login, keychain included, is used); - render, then send (decision 38): the payload is
{argv, stdin, max_tokens};argvis fixed but for the model and the system prompt,stdinholds the untrusted input and the repair errors (fenced and escaped as for every backend; never inargv, whichpsshows),max_tokensthe output budget (passed asCLAUDE_CODE_MAX_OUTPUT_TOKENS, F; it also sizes the stdout cap, the usage floor and the conservative charge).sendrefuses any other payload (invalid_request):argvmust have exactly the template's length and equal it item for item (a shorter or longer list is refused before any item is read, finding 4). The system prompt (SYSTEM_PREAMBLE, then the skill's trusted prompt) goes in--system-prompt, at most 64 KiB (invalid_request); - the flags (answer 3):
-p --output-format json --model <model> --tools "" --strict-mcp-config --mcp-config {"mcpServers":{}} --setting-sources "" --no-session-persistence --disable-slash-commands --permission-mode dontAsk --max-turns 1 --system-prompt <system>. On 2.1.284 every flag is listed byclaude --helpbut--max-turns(hidden), and every one is accepted by the parser (checked locally with an emptyHOME: an unknown option fails withunknown option, these do not). Their behaviour is verified by the live test (tests/test_llm_claude_cli_live.py,@pytest.mark.live, skipped unlessHORAE_LIVE_CLAUDE=1and a token are given, never in CI): no tool runs and none is reported, user settings and their hooks are not loaded, user and project MCP servers do not start, noCLAUDE.mdreaches the model (in the working directory, inHOMEor in an ancestor of the workspace), the system prompt replaces the default one, no transcript or memory is written, no ambient login is used, the output limit is honoured. Each negative assertion has a positive control (finding 2): the same source with the one flag or switch that removes it turned back on must fire its canary first, else the test fails as broken for that release. (E) merge gate, not yet run live: the maintainer runs the live test once and pastes its output into #105's body before the flag set is final and the PR merges.--bare,--restrictedand--safe-modeare not inargv(B):--bare's help says OAuth and the keychain are never read under it, which seems to exclude token auth; the live test prints what each does with the token (evaluation only) and one is adopted only once a live run shows it keeps token auth; - the environment: exactly
PATH(the fixed one),HOMEandTMPDIR(fresh empty per-call directories, 0700),LANG=C.UTF-8,TZ=UTC,DISABLE_AUTOUPDATER=1,DISABLE_TELEMETRY=1,CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1,CLAUDE_CODE_DISABLE_CLAUDE_MDS=1andCLAUDE_CODE_DISABLE_AUTO_MEMORY=1(B),GIT_CEILING_DIRECTORIES(the workspace root, C),CLAUDE_CODE_MAX_OUTPUT_TOKENS(the call'smax_tokens, F; not for the version check) and the token; nothing is inherited (ANTHROPIC_*,*_PROXY,NODE_OPTIONS,CLAUDE_CONFIG_DIRnever reach it), built on the plugin host'sbase_env. To verify live: that the switches stop auto-update, telemetry and non-essential traffic on the pinned release (not checkable from the test: no network capture), thatCLAUDE_CODE_DISABLE_CLAUDE_MDSandCLAUDE_CODE_DISABLE_AUTO_MEMORYdo what their names say (theCLAUDE.mdand memory live tests), and thatCLAUDE_CODE_MAX_OUTPUT_TOKENSbounds the output (its live test; a reportedoutput_tokensabovemax_tokensisoutput_invalidanyway, see the result); - the process (the plugin host's posture, decision 35): an argument list (no shell),
the working directory an empty per-call directory, umask 077, a new session (its own
process group), the per-call directories removed afterwards, also when the caller
cancels the call (the group is killed first; finding 10). The step's timeout, then
SIGTERMto the group andSIGKILL2 s later (timeout, no usage: the ledger keeps the reservation as an estimate); stdout at mostresponse_cap(max_tokens)bytes (1 to 8 MiB, the HTTP backends' body cap, T33;output_invalid, charged conservatively, the group killed at once; finding 7); stderr captured head and tail (64 KiB), its tail drained for at most 1 s after the exit before the reader stops (finding 8), and redacted with every resolved secret before it reaches anLlmError; - (C) the workspace: each call's
home,tmpandcwdare in a fresh directory under<state_dir>/llm-runs(Horae-owned, created 0700, refused when it is a symlink or not this user's, made 0700 when looser), not the system temporary directory, which other users share;GIT_CEILING_DIRECTORIESis that root, so git finds no repository above it (the instance is often one). The factory receives it throughhorae.llm.backends.model_backends(work_dir=...), whichhorae.runner.open_portscalls with<state_dir>/llm-runs; a backend built without one (a test, a library use,horae doctor's version check, which writes nothing in the state directory) falls back to a fresh 0700 directory in the system temporary directory. ACLAUDE.mdin the state directory or the instance is an ancestor of the working directory: B's switch and--setting-sources ""keep it out (live-tested with a control); - (D) managed settings: administrator-managed settings (
/etc/claude-code/ managed-settings.jsonandmanaged-mcp.jsonon Linux, the same names under/Library/Application Support/ClaudeCode/on macOS) apply to everyclauderun and no flag turns them off: they can add hooks, an environment and MCP servers.horae doctorwarns when one of them exists (by name; their contents are never read). They, and remote-managed settings (pushed by an organisation's admin console, not visible as a file), are an accepted residual of T11: they are set by the machine's administrator or the plan's organisation, both already trusted with the token; - the version pin (answers 2, 7):
CLAUDE_CODE_VERSION_RANGE = ">=2.1.284,<2.2"(2.1.284 is the release checked).<command> --versionruns once per backend (one per alias per run), in the same isolated environment without the token; its output must beX.Y.Z (Claude Code). Outside the range, or unreadable, the alias isbackend_unavailablefor the rest of the run and nothing is sent (when the command is a#!script whose interpreter is not on the fixedPATH, the message names the interpreter and says to pointcommandat the native binary);horae doctorruns the same check (an error). Bumping the range needs the live test's output for the new release in the bump PR's body and the version indocs/security.mdT11, and a re-verified retry count of a truncated output (OUTPUT_ATTEMPTS, the amendment below); - the result (answer 5): stdout must be UTF-8 and one JSON object (strict parsing)
with
type: "result".is_error(anything butfalse):api_error_statusthrough the HTTP status table,error_max_turns→output_invalid, a result starting "Not logged in" →auth_failed, elsehost_error(noerror_max_budget_usdmapping: Horae passes no--max-budget-usd, so it is dead code until it does; finding 11); the usage is attached only when the result reports spend (so a refusal releases its reservation, decision 41). A non-zero exit without a result ishost_error. A success needssubtype: "success"(finding 5),num_turns: 1, nopermission_denials, a stop reason other thantool_useormax_tokens, a reportedoutput_tokensno larger thanmax_tokens(else the limit was not honoured:output_invalidwith the usage as reported, the conservative choice, which the ledger flagsover_reservationwhen it passes the reservation; finding 1), and aresultthat parses as one JSON value (no fence stripping;--json-schemais not used, schema validation is #31's); any other result isoutput_invalidwith its usage. Messages are Horae's; the CLI's text never is; - usage and cost (answer 4): tokens from
usage(input_tokens,output_tokens, cache reads and writes), floored as decision 40 K, charged conservatively when missing or unusable.total_cost_usd(a finite number from 0 to 10⁶, else ignored) is notional under a subscription but counts against the step and daily budgets:usdis the larger of it and the alias'priceapplied to the tokens, andpricedistruewhen either is known.may_write_cacheistrue(decision 41: Claude Code caches by itself), so the input bound is priced at the cache write price. (A)priceis required for aclaude-clialias anllmstep uses:horae doctorreports its absence as an error (not a warning), and the backend refuses the first call without one (backend_unavailable, nothing runs), so every call has a dollar reservation before it is made (the notionaltotal_cost_usdis known only after). A price under the plan's notional rates still bounds the call; the larger of the two settles it. Follow-up: pass the remaining stepusdas--max-budget-usd(a second fence) onceCompletioncarries it, with itserror_max_budget_usdmapping; - conformance:
claude-clijoins the backend-agnostic tests oftests/test_llm_backends_shared.pywith a fakeclaude(tests/claude_cli_fake.py); the HTTP-only ones are skipped there with their reason; - the security review (on #105): eleven findings (numbered above where they changed a
rule) and six provisional decisions, A (
pricerequired), B (theCLAUDE.mdand auto-memory switches now;--bare/--restricted/--safe-modeonly after a live run), C (the workspace under<state_dir>/llm-runs,GIT_CEILING_DIRECTORIES), D (doctor warns about managed settings; managed and remote-managed settings an accepted residual), E (the first live run with positive controls in the PR body is the merge gate) and F (CLAUDE_CODE_MAX_OUTPUT_TOKENS), pending the maintainer's review like the rest of this decision. - Amendment (#113, live run): the first live run against Claude Code 2.1.284 (the
haikualias) found three things the fake did not show; the rules above are amended as follows, and with them the whole live test passes (17 tests, every positive control fired). (1) Code fences. With Horae's system prompt the model answers```jsonfenced JSON (also with thinking off), which the strict "one JSON value" rule refused. Aresultthat is exactly one enclosing Markdown code fence (an optionaljsoninfo string, any case, whitespace around it) around one JSON value is now accepted (claude_cli.unfenced): the opening line exactly three backticks and the info string (trailing spaces or tabs, LF or CRLF), the closing three backticks on a line of their own at the end; prose before or after it, two fences, a fence inside text, a one-line fence,~~~or four-backtick fences stayoutput_invalid. The parser is linear string operations, no regular expression (a backtracking pattern was quadratic on a whitespace-only result as large as the stdout cap, blocking the event loop; review of #113).SYSTEM_PREAMBLEis unchanged (it is shared by every backend and part of the LLM cache key).--json-schema(the CLI's structured output) was considered and rejected: it works through an internalStructuredOutputtool (num_turns: 2,stop_reason: "tool_use"), which breaks the one-turn, no-tool invariants. (2) Thinking. The model thinks by default: an{"ok": true}answer cost 126 output tokens (115 of them thinking) and, at a 64-token limit, took a hidden second turn.MAX_THINKING_TOKENS=0joins the switches (B): 13 output tokens,thinking_tokens: 0, one turn, andmax_tokensbounds the answer itself (live-tested with a control: without the switch, the same call thinks). (3) The output limit. An answer longer thanmax_tokensis not cut: Claude Code retries the truncated output on its own up to 3 times, then exits 1 withis_error,subtype: "success", noapi_error_status,num_turns: 4andoutput_tokens4 ×max_tokens(256 at 64). So one call can bill 4 outputs ofmax_tokens: a provider backend now declaresoutput_attempts(1 when absent; an unusable declared value isbackend_unavailable, one aboveMAX_OUTPUT_ATTEMPTSis clamped to it;claude-cli:OUTPUT_ATTEMPTS = 4), carried onPreparedRequestandRenderedRequest;worst_case(decision 41) reservesoutput_attempts × max_tokensoutput tokens, andmax_tokensdivides the step's remainingtokens_outandusdby it so that the reservation still fits the step's budget (aclaude-clistep withtokens_out: 2000getsmax_tokens500; the alias'max_output_tokenscaps each output, not divided). So authors should size a step'stokens_outandusdfor 4 outputs when its alias isclaude-cli. The conservative charge and the stdout cap cover 4 outputs too. On a success the bound staysmax_tokens(num_turnsmust be 1: one output). Anis_errorresult with no HTTP status whose reportedoutput_tokensis at leastmax_tokens, and that shows the CLI's own retry or limit handling (more than one turn or asuccesssubtype; with neither it stayshost_error), is nowoutput_invalid("the output was truncated at the limit", on the reported count, never the CLI's text); it washost_error. It is charged its reported usage, its output at leastOUTPUT_ATTEMPTS × max_tokenswhen it took more than one turn (the CLI billed the retries even if a release reported only the last one). The live output-limit test also checks the reported output is at most 4 ×max_tokens. The retry count is the CLI's behaviour, not a documented contract: bumpingCLAUDE_CODE_VERSION_RANGEmust re-verify it live (and changeOUTPUT_ATTEMPTSif a release retries more or fewer times). The same run printed that--restrictedand--safe-modekeep token auth (a success) and--baredoes not ("Not logged in"); none is adopted (B: a separate decision).
- contract change (optional):
Provisional decisions (#53, pending maintainer review)¶
- Secret redaction in logs and run records (#53, design note and maintainer answers on
#100; security review findings and maintainer decisions on #106). (39 and 42 are taken
by #27 and #29.) Contract change: none; a store migration (
0005_secret_flags). The store's findings reuse thesecret_in_outputviolation of decision 35 (so a replay leaves them out of the compared violations, as it does for the host's). Maintainer decisions (binding, on #106): the journalledafter/actual_afterbytes are exempt and flagged only for a secret new compared tobefore(C), and secrets under 8 bytes are refused (H). Provisional, pending maintainer review: B (identifiers exempt and flagged), E (every logger, warnings, exception hooks), F (secure_delete), G (key collisions). Rules ofhorae.secrets, the store, the engine, the LLM layer and the CLI:- A. one shared redactor and a process registry.
Redactor,token,SecretInKeyand the encodings of decision 35 C moved tohorae.secrets.redact(re-exported byhorae.plugins.host.redact); the log scrubber tohorae.secrets.logs(re-exported byhorae.plugins.host.logs). EverySecretResolver.resolveadds the secret to a process registry (remember;current()is aRedactorof every secret this process resolved, rebuilt when the set grows; it only grows, so a rotated value stays redacted).Instance.prime_redaction()resolves, for redaction only, every secret the instance names (secrets.refs, the secretshorae.lockgrants, the model aliases'secret), skipping one that cannot be resolved;Runner.runand the CLI commands that read the instance call it first; those that readhorae.yamlalone (runs,diff,usage,undo) prime the same names (horae.config.loader.redaction_names(config, lock), shared with the instance), readinghorae.lockbest effort (an absent or invalid lock adds nothing). A provider backend still resolves its own key lazily, through its own resolver. A JSON number whosejson.dumpsis a secret's value is a numeric match (pin: 12345678): the checks that refuse see it (Redactor.find), the host and the CLI redact it, the store flags it without changing its type; - B. what is redacted, and identifiers (provisional). Only free text is
rewritten. Identifiers the system needs are exempt and flagged (kept as written,
neither refused nor rewritten; a hit is a
secret_in_outputviolation): run ids, pipeline names, timestamps, statuses, kinds, plugin names and refs, tokens, digests, the journal'starget,applied_byandsink_identity, a task'sfingerprint,sourceandtarget, notification keys, the usage ledger'salias,backendandmodel, a run'shost, the pipeline definition. Rewriting them made the record invalid (a run refused for a secret that happened to equal a word of its own structure), broke undo (a redacted journal target no longer names the note) and replay. Only the LLM cache refuses. The free-text allowlist (horae.store._gate): stepoutput,error.message,stderr, callparamsandintents; inputparams,dataandintents; the intent payload fieldscontent,heading,title,body;context.varsvalues; LLMrequest,response,intents,repair,schema_errors; violation details; the run'serror; a task'stitle; an abandoned run'serror. A pipeline definition holding a secret's value is not copied into the record (pipeline_definitionisNone; its parameters refuse the run at plan time); - C. the store's secret gate (answers 1–3), fail safe. Every table, just before
writing, with the registry's redactor: free text redacted (JSON: string leaves and
object keys), identifiers and numeric matches flagged (B). Refused
(
SecretRefused, anInvalidRow, nothing written, name only): an LLM cache entry holding a secret in any string, key or number (answer 3; callers treat it as "do not cache",Store.cache_put_safe, for #32), and, as a residual, a record or step that would no longer validate once its free text is redacted (a token longer than the room its field has left). The journalledafterbytes and a sink'sactual_afterbytes: exempt, and flagged only when the secret is new (maintainer decision on #106): kept byte for byte (apply's mismatch check and undo depend on them); a hit is recorded only when the secret occurs more often than in the journalledbefore("the store found secret X in the content Horae wrote to, not in the note before"), so a secret the user already had in their note is not flagged. Exempt (answer 2): the journalled beforebytes and the bytes a forced undooverwrote, the user's own note, which undo restores byte for byte (docs/security.md T09). Every finding is logged (horae.store, names only) and kept in thesecret_flagstable, in the same transaction as the row that held it;save_runturns a run's findings (and those in the record itself) intosecret_in_outputviolations, then deletes them, so a record saved by anotherStoreor process still gets them;abandon_rundeletes them (no record); when the violations would passMAX_ITEMS, the rest is aggregated into one violation; - D. trusted inputs are refused (answer 4). The engine fails the run at plan time,
before any call,
params_invalidnaming the secret only, when a template variable (horae run --var) or a rendered parameter holds the value (or a known encoding) of a resolved secret, in a string, an object key or as a number's whole value; the variable is redacted in the record'scontext. A skill's prompt or output schema holding one (in a string, an object key or as a number's whole value) is refused at plan time too:_planloads the skill through the engine'sSkillSource(#27, decision 39) and fails the run withparams_invalid(<skill>: the prompt or output schema holds secret <NAME>) before any step runs.ModelBackends.preparekeeps the same check as a backstop (an engine given noSkillSource, aPromptSourcethat reads other files), before rendering, reserving or sending.params_invalidreleases a ledger reservation; - E. logs, warnings, uncaught exceptions (provisional).
horae.secrets.logs.install()(the CLI entry point,Runner.run, an openingPluginHost; idempotent) wraps the log record factory: every record of every logger (the root,asyncio,urllib3,py.warnings,uvicorn,openai,mcp... not a list of prefixes any more) is redacted when it is created (message formatted and redacted with the registry and every open host,argsdropped,exc_infoandstack_inforeplaced by the exception's type name), whatever handler sees it. It also callslogging.captureWarnings(True)and setssys.excepthookandthreading.excepthookto hooks that redact the report they print. The HTTP loggers are pinned toWARNING. The LLM layer:ModelBackends.sendredacts what a provider backend returns (anLlmError's message and stderr, raised again as a new error with no__cause__/__context__; the output, intents and schema errors; logged by name); the engine redacts anLlmErrormessage from anyLlmBackendbefore recording it. The pipeline digest and the cache key are computed on the real values (they are hashes); - F. deleted bytes (provisional). Every writable store connection (the main one and
the heartbeat's) sets
PRAGMA secure_delete = FAST, so a deleted or replaced row is zeroed where SQLite rewrites its page anyway. A database written before #53 can hold unredacted values in rows and free pages: docs/operations/retention-and-backups.md documents a one-offVACUUM; - G. key collisions (provisional). When redacting two keys of one JSON object gives
the same text, the later one is renamed
[REDACTED:NAME]#2(#3...) and a violation says so: nothing is lost silently; - H. short secrets (maintainer decision on #106; supersedes decision 35 D). A
declared secret shorter than 8 bytes of UTF-8 (
MIN_SECRET_BYTES) is refused when it is resolved:SecretError"... is too short for reliable redaction (min 8 bytes)", never echoing the value.horae doctorreports it as an error; a plugin that declares it fails withsecret_missing, a model alias with its backend's secret error (the run needing it is refused); priming skips it with a warning naming it (horae.secrets). The redactor has no short-secret case any more (RedactorraisesValueErrorif it is handed one), and the host no longer warns about one; - I. CLI output. Every command prints through
horae.cli_output.echo, which redacts the text;to_jsonscrubs the document as data first (numbers too, so the JSON stays valid).horae.apply.render.saferedacts before it escapes control and invisible characters, and text is redacted before it is cut (an HTTP body at 200 characters, a run's error at 4096), so neither a secret holding such a character nor a secret cut in half slips through. An identifier holding a secret is printed redacted (B keeps it in the store, not on the terminal); - limits: unknown encodings are not recognised and only the leftmost match of two overlapping secrets is replaced (decision 35); the gate knows only the secrets this process resolved (primed from the instance); an 8-byte secret still matches inside unrelated text that contains it (the reason identifiers are flagged, not rewritten); a secret in an identifier is in the store (flagged), but not in the logs nor the CLI.
- A. one shared redactor and a process registry.
Provisional decisions (#31, pending maintainer review)¶
-
Schema-validated output with one repair retry (#31). (42 is taken by #29.) Contract change: none (
llm[].schema_valid,repairandschema_errorsexist since decisions 21 and 33;validator_unavailableis a new step error kind, anErrorKindstring). Rules ofhorae.llm.validate,horae.llm._schema_errorsandModelBackends. A security review of the first implementation found 8 issues; review decisions A to F below are provisional, for the maintainer to confirm:- A. the validator is the default (review decision D):
ModelBackends.validatedefaults tohorae.llm.validate.validate_output(imported lazily:horae.llm.validateimportshorae.skills, which importshorae.llm.base), and so doeshorae.llm.backends.model_backends(whatopen_portsbuilds), so decision 38 G holds for everyModelBackends, not only the one the runner builds. The only opt-out is the explicit sentinelhorae.llm.UNVALIDATED(test doubles of the backends). AValidatoris calledvalidate(output, schema, timeout_s=...)and may return an awaitable; a synchronous one (test doubles) runs inline; - B. what is validated: the provider's parsed output, before the reserved
intentsare split off, against the skill's full output schema (RenderedRequest.output_schema, the skill file; never the provider's transformed copy, which drops constraints:anthropic.transform_schemamovesmaxLengthinto a description, and the validator still reports/x: maxLength), withjsonschema'sDraft202012Validator. Formats are annotations (draft 2020-12's default): asserting them would depend on optional packages (rfc3339-validator...), so the same output would be valid in one install and not in another. Then the reservedintents, when present, must be an array of objects. First, in the parent, the output re-serialised as decision 39 E bounds it (compact,ensure_ascii=False, UTF-8) must fitMAX_OUTPUT_BYTES; a larger one is the single repair errorSIZE_ERROR(the model's fault) and never reaches the worker; - C. a killable, isolated worker: each validation runs in a fresh child process, awaited through asyncio pipes, so the event loop is never blocked:
interpreter sys.executable -I -B horae/llm/_schema_errors.py(isolated: noPYTHON*variables, no user site, not the script's folder onsys.path; no bytecode written)environment empty ( env={})descriptors stdin (the request) and stdout (the answer) pipes, stderr /dev/null, nothing else (close_fds)working directory /session its own ( start_new_session): no signal of the terminal reaches itCPU RLIMIT_CPUof the timeout plus one second, set by the worker on itselfmemory RLIMIT_ASatMAX_WORKER_MEMORY(256 MiB; the worker is about 26 MiB oncejsonschemais imported),RLIMIT_DATAwhere that cannot be set; macOS refuses both, so the ceiling is Linux only there (review decision A). An allocation past it is aMemoryError: exit status 3,WORKER_ERRORtimeout min(VALIDATION_TIMEOUT_S, the attempt's remaining deadline - VALIDATION_MARGIN_S)(10 s and 0.5 s; the interpreter start included), then killed and reapedcancellation the awaiting task cancelled (the step's or the run's deadline): killed and reaped answer read with a bound: at most MAX_WORKER_OUTPUT+ 1 bytes (64 KiB), a longer answer is not read and the worker is killed; it must be a JSON array of at most 16 strings of 1 to 200 charactersNot a thread (it cannot be stopped) nor a process pool (one task cannot be killed without breaking the pool, and a forked pool inherits the parent's resolved secrets, descriptors and threads). The cost is one interpreter start, about 0.5 s with
jsonschema, at most twice perllmstep. The worker imports only the standard library andjsonschema(nothing ofhorae, no instance state).horae doctorchecks, when a pipeline has anllmstep, thatsys.executableand the worker script exist and that a trivial validation, run exactly as above, gives the expected error (horae.llm.validate.worker_problem); - D. fail closed, and no repair for the validator's own failure (review decision C): a timeout (/: timeout: the output could not be validated in time), a worker that cannot start, exits non-zero or answers anything else (/: validator: the output could not be validated), an unusable schema (/: schema: ...) or an output that is not plain JSON (/: json: ...) is never a pass:validate_outputraises, andModelBackendsraisesLlmError("validator_unavailable", <that fixed message>, usage=<the attempt's usage>)(so does any exception of another validator:the validator failed (<type>)). It is not the model's fault, so no repair is made: the step degrades at once with kindvalidator_unavailable, its cost charged to the run and settled in the ledger (decision 41). No intent of the attempt is kept, as for any failed attempt; - E. repair errors carry no data: each error is<pointer>: <keyword>: <description>, where the pointer holds array indexes and property names the schema declares only (any other segment is*; at most 120 characters, cut on a segment), the keyword is the failing JSON Schema keyword (falsefor afalseschema,invalidfor an unlisted one) and the description is Horae's fixed wording, with at most a number or type names taken from the schema (trusted, the skill author's). Never an instance value, an excerpt of the output, an undeclared key, orjsonschema's own message (which quotes the value). The errors are de-duplicated, sorted in the natural order of their pointers (segment by segment, an index before a name, indexes by value:/b/2before/b/10; then by keyword and description), at mostMAX_ERRORS= 16 (the last one then says how many more there were) of at most 200 characters each; at most 1000 failures are examined. One output and one schema give one list, so a live run sends the same repair for the same output; a replay serves the recorded errors (horae.replay), so a later change of this order (or of the wording) changes no replay of a recorded run, but changes what a new run records. The provider backends still frame the errors as data inside<schema_errors>(decision 38). The repair attempt sends the same viewed input, prompt and schema plus these errors: nothing new; - F. an invalid output proposes nothing: when the validator reports errors,ModelBackendsdrops the output'sintentswhatever their shape (LlmResponse.intentsis empty, soLlmCall.intentsof an invalid attempt is[]; a non-listintentsis a schema error, no longeroutput_invalid). The engine (unchanged) routes and keeps nothing from an attempt with schema errors, makes exactly one repair attempt with the remaining step budget (and, through the ledger, the remaining daily allowance; decision 41), and after a second invalid output degrades the step (schema_invalid): no intent of the step enters the record, later steps are skipped, the run isdegraded, whichhorae runsshows (and--status degradedlists); - G. a schema cannot make one validation exponential (review decision B): the loader caps the product ofanyOf/oneOfbranch counts along any path of the output schema,$refs followed (memoised per$ref), atMAX_COMBINATOR_FANOUT= 1024, elseskill_invalid(decision 39 E, amended). An 18-level$defschain that branches twice per level (2^18 paths) is refused; alternatives side by side (inproperties,allOf) do not multiply. What the cap does not bound (ananyOfover a long array keeps every branch's errors for every item) the worker's memory ceiling does; - H. the deadline and the attempt's cost (review decision E): the validator is given what is left of the attempt's deadline lessVALIDATION_MARGIN_S, so it times out (D:validator_unavailable, the usage charged) before the engine's own deadline cancels the step. Should the step or the run be cancelled during the validation all the same, the cancellation carries the attempt's usage (horae.engine.ports.attach_usage/attached_usage): the ledger settles with it (not with the reservation as an estimate) and the engine adds it to the run's cost; - I.jsonschemais pinned to one minor version (review decision F): `jsonschema=4.26,<4.27
. Which outputs are valid, and which errors (keyword, path, order) a repair sends, depend on the validator's behaviour, so its version is part of the replay contract: the record holds the errors sent, and a new minor version is an explicit upgrade (with this decision's tests), not a silent change between installs; - **follow-ups**: a warm worker if the start-up cost matters (#29's CLI backend is slower anyway); a memory ceiling on macOS (none of itssetrlimit` limits applies); #51 (sandboxing plugins) may reuse the worker's isolation. - A. the validator is the default (review decision D):
Provisional decisions (#32, pending maintainer review)¶
-
The LLM cache and the $0 path (#32). Numbering: 44 is #31's (PR #108), opened in parallel. Neither is renumbered: whichever of the two merges second places the #31 section (44) before this one, so the list stays in order. A compatible v1 addition to
horae.yamland the rules ofhorae.runner._cache, the engine,horae undoand the newhorae cache purge:- contract change (optional):
horae.yamlcache: {ttl_s?, max_entries?}, integers;ttl_s60 to 31622400 (366 days), default 604800 (7 days);max_entries1 to 100000, default 1000. Not part ofconfig_digest(decision 33 D3): it changes what is reused, never what a replay computes; - one source. The store's
llm_cachetable is the single source of reusable outputs for live runs; the runner no longer readsStore.last_accepted_llm(D2, decision 30), which stays for tools and tests. Migration 6 adds the indexllm_cache_created(oncreated_at, which trimming orders by). A store upgraded from before #32 starts with an empty cache: its first run per input calls the model once; - two keys (G). The engine key (
RunRecord.input_hash, unchanged: SHA-256 of the canonical JSON of the skill, the skill plugin's name, version and commit, the resolved model, the viewed input, and with a loaded skill itsskill_versionandskill_digest, decision 39) is what the run records and what replay and undo use. The stored key (StoreLlmCache.stored_key) is SHA-256 of{input_hash, alias, version}:aliasis the step's model alias ashorae.yamldeclares it at the time, withoutsecretandpriceand without unset fields (backend, model,base_url,structured_output,max_output_tokens,max_tokens_field, and a later field such as theclaude-clicommand),versionisLLM_KEY_VERSION(horae.llm.backends._shared, bumped wheneverSYSTEM_PREAMBLEor the request framing changes; a test pins the preamble's digest to it). So the same model name on another backend or endpoint, or with another output mode, is a miss; a new price is not. The entry'sresponseis{output, intents, backend, model, skill_version, input_hash, run_id, created_at}(input_hashthe engine key,run_idthe producing run); itstokens_*andcost_usdare what producing it cost (both attempts), for information;
engine key ( input_hash)stored key ( llm_cache.key)skill name, version, digest yes via input_hashskill plugin name, version, commit yes via input_hashresolved model name yes via input_hash, and inaliasviewed input yes via input_hashalias backend, base_url,structured_output,max_output_tokens,max_tokens_field, commandno yes alias secret,priceno no LLM_KEY_VERSION(preamble, framing)no yes pipeline, act/notify bindings no no (re-checked on reuse, C) - the engine reads, the runner writes. execute(cache=LlmCache): the engine awaitscache.lookup(key, model_alias=..., output_schema=...)whenpreviousdoes not matchthe key; a hit is reused exactly as D2 (no backend call, LlmCallwithcached=True,zero usage and the request marker {skill, model, reused_input_hash, source_run},source_runthe producing run; intents validated and routed again; a reuse whoseintents no longer route is a miss; the same step and run statuses: noopwhen nothingis proposed). A hit names the alias' current backend and model (equal to the stored ones, since they are in the stored key, unless the alias is no longer declared). No backend call means no ledger row: a cached output is charged zero (decision 41). An exception from lookup, or an entry for another key, is a miss. A store error whilereading, writing or purging is logged (type only) and never fails the run; rule when write ( remember, after the record is saved)the run is okornoop(H: notdegraded,failedorundone), not a dry run (D); thellmstepok; its last call schema-valid with recorded intents; no call of the step a reuse (a hit never extends an entry); no resolved secret in the entry (cache_put_safe, decision 43); two processes writing one key: the last write winsread ( lookup)not --no-cache; the entry exists,expires_atnot passed andcreated_atwithin the currentttl_s(A); well-formed (else deleted); the full output (the output with its reservedintentsput back) passes the skill's full output schema (F, else deleted); its intents still validate and route in this pipeline (C)delete expiry and max_entriesat the start of each non-dry run (first in, first out); invalid on read (F);horae undoof a run (B);horae cache purge(E)- (A) bounded staleness. An entry is live for ttl_sfrom when it was produced (itsexpires_at, and alsocreated_atagainst the currentttl_sat lookup: loweringttl_sapplies at once to every entry; raising it applies to entries written from thenon). A hit does not extend it: an unchanged input asks the model again at most once per ttl_s(PLAN.md §2.2's "no LLM call when inputs unchanged" holds within that window).After expiry a non-deterministic model may answer differently, so an unchanged input may produce new intents and notifications once per ttl_s(appliers still deduplicatewhat is identical). At the start of every non-dry run, entries past ttl_sor theirexpires_atare deleted, then the oldest beyondmax_entries(Store.cache_trim,first in, first out: a hit does not make an entry recent), best effort; - (B) undo invalidates. When horae undomarks a runundone, every entry for thatrun's engine key is deleted in the same store transaction ( Store.cache_delete_input,which matches the input_hashthe entries record, whatever alias they were storedunder), also when the undone run was itself a cache hit: running the same input again asks the model instead of re-applying what was just undone. A partial undo (not every change undone) leaves the entry; - (C) cross-pipeline and cross-history reuse stays. Any earlier accepted output is reused, not only the last run's (input A, B, then A again makes two calls), across processes, and across pipelines that run the same skill, model alias and viewed input. This is safe because routing and bindings are re-checked on every reuse: an intent whose explicit target is bound differently in the other pipeline does not route, which is a miss (the model is called); - (D) dry runs read, never write. A dry run reuses a live entry (a preview costs nothing on unchanged input) but neither stores its output nor purges: a preview must not change what later real runs do; - (E) horae run --no-cache(debugging) skips the lookup: the model is called even onunchanged input, and its accepted output still replaces the entry (a fresh answer is a valid answer). Runner.run(cache=False)is the same. **`horae cache purge [--all--older-than DAYS] [--skill NAME] [--json] ** deletes entries on demand (--skill`alone: all of that skill's): it opens the store writable but never creates it, takes no lock, prints how many entries were deleted and how many remain (`{schema_version, instance, all, older_than_days, skill, deleted, remaining}`); exit codes per decision 37: 0 purged (possibly nothing), 1 configuration or store problem, 2 usage error (nothing selected, --allwith--older-than), 70 internal;- (F) re-validated on read. A cached output is checked against the skill's full output schema at every lookup, by the validator of the backend path: #31's horae.llm.validate.validate_output(default_validator; the interim synchronouscheck_outputis removed with #31, so no validation runs on the event loop), with itskillable worker, CPU and memory ceilings, at most CACHE_VALIDATION_TIMEOUT_S(10 s),and the loader's fan-out cap on the schema (decision 44 C, G). An entry that fails, or that cannot be validated (fail closed; validator_unavailableon a cache read is amiss, never a degraded step: the model is then called), is a miss and is deleted. So an entry written before a validator existed, or tampered with in the store, is never reused unchecked; - replay stays exact. Replay never reads the store's cache: a run that reused an entry is replayed with that output as previous(recorded_previous, decision 33, whichkeeps source_run), so the replay takes the same path; a run that called the model isreplayed from its tape; - follow-ups: a per-skill ttl_s; LRU instead of first in, first out if hit ratesshow it matters. - contract change (optional):
Decisions (#35, design note and maintainer answers on #99)¶
- The action guard on LLM proposals (#35). Numbering: 44 is #31's (PR #108), 45 #32's.
No contract change: the run record's
violations[].kindalready hasguard, and the step'serror.kindis the free-formErrorKindguard_violation.horae.engine.guardruns on every batch of intents thellmstep proposes (fresh,previousor a cache hit), after schema validation and the permission check, before routing:- (1) per-type limits. A skill's
intents: {type: max}(decision 39 F) caps the intents of each type per step; more is a guard violation (it wasintent_rejected). A type the skill does not declare staysintent_rejected(a permission breach, the run fails); - (0) structurally conservative (security review): rather than chasing each obfuscation, the guard refuses whole classes of text the parsers it guards against could read differently: control and format characters, any non-trivial tag-like token, any link destination with whitespace or a backslash (rules 0a, 0b, 3, 5);
- (0b) Markdown escapes. A renderer drops
\before ASCII punctuation, so the text it renders differs from the text as written ([x](java\script:…),<https\://…>). Every check also runs on a view with those escapes removed (after each entity-decoding pass), and the text is refused if any view fails. A backslash is refused outright inside a link destination, a reference definition and a tag-like token or autolink; - (0a) no control or format character. Any Cc character but
\n(tab and carriage return included), any Cf character (zero-width, joiners, bidi controls, BOM, soft hyphen) and U+2028 / U+2029 refuse the text before any other scan, also when an entity decodes to one (h	ttps:). Note text already refused lone CR and U+2028 / U+2029 (content_line_break); this extends it to all guarded text. A ZWJ emoji sequence is refused too (known cost); - (2) embeds are always refused, even when the URL is in the input (they fetch when the
note renders, without a click): any
![(Markdown and reference images, Obsidian![[…]]embeds); - (3) tag-like tokens: an allowlist, exact form. Every
<followed by a letter,/,!or?starts a tag-like token, up to its>. It is allowed only as exactly<name>,</name>or<name/>with a name ofb i u s em strong code pre br hr p ul ol li blockquote h1–h6 kbd sup sub mark del(no attribute, no:, no space), or as an autolink: content up to>thaturlsreads as one URL with ascheme://or a special scheme, and no whitespace, quote or=(the URL then goes through (4)). Everything else is refused: other tags (img,iframe,svg,a,div,span, custom elements…), any attribute (on*,style,background,poster,srcset,ping,href, so alsourl(and@import),<name:…>forms, comments, doctype, processing instructions and an unclosed<b. A denylist of embed tags, then an autolink exemption, were rejected in review; - (4) URLs. Backslashes are read as
/first (https:/\host,\\host). A URL is a run (up to whitespace,<,>or a control character) starting atscheme:followed by/(any[a-z][a-z0-9+.-]*, whatever precedes it), at a scheme ofhttp https ftp ws wss obsidian mailto javascript vbscript data file blobfollowed by any non-space character (ftp:host), at//at a token boundary (protocol-relative, not after a scheme character,:or/), or atwww.at a word start. A URL with a refused scheme (javascript vbscript data file blob) is always refused. Every other URL (answer 3) must be an exact string extracted the same way from the viewed input (string values and object keys of what the model was shown), case-sensitive, after dropping at most 16 trailing punctuation characters (.,;:!?)]}'"*_~and backtick) on either side. So a known URL may be copied, but never extended (…?q=<data>,…/<data>). Anotify.pushlinkmust be exactly such a URL and fall under the entry'slink_prefix(decision 30). A per-pipelinestrict_links(only trusted parameters andlink_prefix) is a follow-up; - (5) link destinations. After
]((up to the next), or the line end when there is none) and after a line's leading[label]:(not a[^footnote]:; up to the line end; container prefixes skipped, (H2)), leading spaces skipped: a destination holding any whitespace or backslash (so also a title,[x]( javascript :…)or a line break) or starting with a refused scheme (also inside<…>) is refused; its URLs go through (4). A refused scheme in prose (data: three items: colon then a space) is not a link in Markdown and passes; - fields scanned:
note.*contentandheading,task.createtitleandfingerprint,notify.pushtitle,bodyandlink, every string and object key of anhttp.postbody. Targets bound by routing (path,http.posturl) are not text; - robust parsing, bounded work. Every check runs on the text as written and on its
HTML-entity-decoded forms (up to three passes:
<img,&lt;img) and their Markdown-unescaped forms (0b), ASCII case-insensitively. Scans are linear (findloops that resume after each match, regular expressions without nested quantifiers, pointers to the next), line end or whitespace reused while ahead); a test scans 1 MiB of hostile text per field, and a seeded fuzz (case flips, decimal and hex entities, Markdown escapes, controls and format characters inserted into embeds, script links and unknown URLs) never passes; - (answer 4) the whole step degrades. A violation records one
Violation(kind="guard")and the stepdegradedwitherror.kindguard_violation: none of its intents is routed (also the valid ones), its output is not used, later steps areskipped, the run isdegraded, and noinput_hashis recorded (so the runner never caches it). The LLM call is recorded with its raw intents (replay and audit); - (answer 6) content-free detail.
Violation.detail(= the step error's message, at most 512 characters) names only closed-set values: the proposer (skill:<name>), the intent type and position, the field and the kind of problem, e.g.skill:daily-brief/ rank proposed note.create #2 with an image or embed in `content`, never the URL, its host or the text. The same line is logged atwarning(horae.engine); - reuse (decision 45). On a reuse, a guard violation is a cache miss: nothing of
the entry is recorded (no violation) and the model is called. For a cache hit the engine
awaits the cache's
discard(key, model_alias=...)(a port member, (H4));StoreLlmCache.discarddeletes the entry (logged, store errors swallowed), so a poisoned entry is not looked up again. A refusedprevious(replay) is only a miss; - (answer 5) scope. LLM proposals only;
collectandtransformintents are not guarded in v1 (first-party plugins in the D tier, T04); hostile plugins are #52's; - fencing (design note C). The backends already fence the input: it is sent as JSON
inside
<input>tags with every<written<(horae.llm.backends._shared. escaped), and repair errors likewise inside<schema_errors>, so data can never close the fence (tests/test_llm_backends_shared.py). A per-call nonce adds nothing to that and would make requests non-deterministic, so none is added andLLM_KEY_VERSIONis unchanged; - known limits: obfuscated URLs that are not links in Obsidian (
hxxps://) pass; zero-width and other format characters are refused (0a); a URL the input brings may be copied (tenet 5 as written); a brief citing a new URL from the model's own knowledge is refused; being conservative, a Windows path (C:\x),a:/b,x<b and c(an unclosed tag-like token), a Markdown link title and a ZWJ emoji not in the input are refused too. - hardening round (provisional, pending maintainer review). Conservative: v1
protects the Obsidian rendering surface, not only CommonMark. In text bound for a
note or a notification (every guarded field but
http.postbody), on every view: - (H1a) active code fences. A fence of three or more backticks or tildes, after any
leading spaces (more than CommonMark's three too), blockquote
>or list prefix, whose info string starts (case-insensitively, after spaces or{) withdataview,dataviewjs,templater,mermaid,js,javascript,html,buttonorquery(ACTIVE_FENCES): Obsidian or a common plugin runs, queries or draws these instead of showing code. Other fences (python, none) pass; - (H1b) Templater and inline queries.
<%and%>anywhere (Templater, inline script),`=and`$=(Dataview inline queries, their default prefixes); - (H1c) frontmatter. In a note intent's
content(all threenote.*types), a first non-blank line of three or more-(a frontmatter block can setcssclasses, aliases and plugin properties). This complements decision 32's note conventions (content_has_marker,content_line_break); a thematic break later in the text passes; - (H1d) Mermaid
click.click <id> href,click <id> callorclick <id>then a quote, at a line's content start or after a;, anywhere (also outside a fence, although (H1a) already refuses amermaidfence). A callback without a quote (click A cb) is not matched: it needs a Mermaid block, which (H1a) refuses; - (H1e) wikilinks. A
[[…]](up to]]or the line end, alias included) holding://or a refused scheme (javascript:…) is refused; plain internal wikilinks ([[Daily/2026-10-27|today]]) pass. Embeds![[…]]stay refused by (2); - (H1f)
obsidian:URIs must be in the input set like any URL (4); a miss is reported as its own kind (an obsidian URI not in the input), and the case-sensitive match meansOBSIDIAN://…is refused unless written so in the input; - (H2) container prefixes before link definitions. Before a
[label]:, any spaces and tabs, blockquote>and list markers (-,*,+,1.,1), followed by a space, a tab or the line end) are skipped, repeatedly (> - [r]: javascript:x). A footnote definition[^x]:is not a link definition but gets no exemption: its text goes through the URL, embed and tag checks like any other text (an unknown URL in a footnote is refused); - (H3) entity decoding fails closed. When a fourth
html.unescapewould still change the text after the three allowed passes, the text is refused (too many levels of HTML entities): the guard never checks a text whose rendering it has not seen. Text with four or more nested&levels is refused (known cost); - (H4)
discardis part of theLlmCacheport.LlmCache.discard(key, *, model_alias)is now a Protocol member, so mypy rejects a cache without it;horae.engine.NoDiscardCacheis an abstract base whosediscardis a documented no-op (a refused hit then stays a miss each lookup, never routed). The engine awaits it directly (exceptions still ignored). A refusedprevious(replay, decision 33; the D2 reuse of decision 30) is not a cache entry: it is only a miss and is left as is; - (H5) logging and source. Details and the
warningline stay content-free. The guard'ssourcemust beskill:followed by the pipeline configuration'sSkillRef(<namespace>/<skill>, pattern-checked, at most 128 characters); anything else is aValueError(a programming error, never input or model text); - (H6) ADR 0002 keeps its accepted text; what #17 and #35 added after acceptance is a dated amendment at its end;
- bounded work: the new scans are line loops and
findloops that resume after each match (wikilinks reuse the next]]and line end), plus one regular expression without nested quantifiers (click); a test scans 1 MiB per hostile shape.
- (1) per-type limits. A skill's
Provisional decisions (#34, pending maintainer review)¶
- De-identification before a cloud model, and no secret in a request (#34, design note
docs/design/0034-deidentification.mdand the maintainer's answers on PR #98). Numbering: 46 is #35's (the action guard). Compatible v1 additions tohorae.yamland the run record, and the rules ofhorae.llm.deid,horae.llm.base, the engine and the cache:- (A) local or cloud, explicit.
models.<alias>.local: true | false(optional, strict boolean). Unset:ollamais local, every other backend (anthropic,claude-cli,openai-compatible) is cloud (LOCAL_BACKENDS,ModelAlias.is_local); never inferred frombase_url.horae doctor's price warning now applies to every cloud alias by this rule (replacing decision 40'sCLOUD_BACKENDS): anopenai-compatiblealias withlocal: trueis not warned, anollamaalias withlocal: falseis.localjoins the alias' part of the cache's stored key andconfig_digestonly when set (an unsetlocalis left out of both, so the digests of an instance that does not use it are unchanged and old runs replay without a "horae.yaml changed" error); - (B) what is declared. Field classes in the skill's input view (#27, decision 39:
path: {class: person|email|phone|place|amount|free_text},amountalsobuckets: [numbers]), plus an optional vocabulary:horae.yamldeidentification: {vocabulary: <file name>}, a file ofsecrets.dir(personal data: never in the instance repository) read like a secret file (SecretResolver.read_file: one path segment, a regular file of at most 64 KiB, opened once; not registered for redaction). Its format is oneclass: termper line (person,email,phone,place;#comments; 2 to 200 characters, no control character, at most 4096 terms); a plain format, not YAML, so no alias expansion and no parser echoing content. Errors name the line, never the term.horae doctorreports an unusable vocabulary as an error; - (C) the transforms (
horae.llm.deid.pseudonymize, a pure function of the viewed input, the classes and the vocabulary): every scalar leaf and every object key under aperson,email,phoneorplacefield becomes[PERSON_1],[EMAIL_1],[PHONE_1],[PLACE_1](a value overMAX_VALUE_CHARS, 1 KiB, is withheld as[PERSON], not reversible); anamountbecomes a bucket label (<0,50-200,>=1000; default bounds 0, 10, 100, 1000, 10000;[AMOUNT]for a value that is not a finite number), not reversible. Every other string of the viewed input and every object key (free_textfields and unclassed ones alike: provisional B below) is scanned for the known values: the vocabulary terms, the values of this input's token-class fields (so "Lunch with Bob" is covered when Bob is an attendee) and each name part of apersonvalue or term (at least 3 letters, mapped to the whole name's pseudonym: provisional C), replaced by their pseudonym; a phone's last 9 digits with any[\s.\-()]separators and up to 4 digits of prefix; an amount's renderings (provisional D), replaced by its bucket label. Matching: the string is NFKC- normalized and stripped of format characters (zero-width, bidi controls, soft hyphen), cut into tokens (letter runs[^\W\d_]+, digit runs, white-space runs, other single characters), and compared token by token with the known values (letters case-folded on both sides,STRAUSS=Strauß; any white-space run, NBSP and ideographic space included, equals any other): a known value matches whole letter runs only (Aliceinalice_smith,user_alice,alice123; not inMalice), leftmost then longest. A trie over the tokens, at mostMAX_TERM_TOKENS(48) deep: linear in the text whatever the number of terms (600 KB and 4096 terms well under a second). A string in which nothing is found is sent byte-identical. Text of the input shaped like a pseudonym ([PERSON_1], any case, fullwidth brackets after NFKC) is first neutralized to(PERSON_1)(countedneutralized), so the model can never be handed a pseudonym that re-identification would turn into a real value. Two keys of one object that are the same once pseudonymized fail closed (deid_unavailable). A classed path under another classed path is refused (DeidError, a defence in depth: the skill contract already refuses overlapping view paths); - (D) stable per run, no key (maintainer answer 3). Pseudonyms are numbered per
class in order of first occurrence: the classed leaves and keys in canonical order
(sorted keys, array order), then the matches in scanned strings; the same value
(the same tokens) keeps its pseudonym. The same input always gives byte-identical
requests, so a replay or a cache hit recomputes the same mapping. Cross-run stability
(keyed HMAC) is a later option.
DEID_VERSIONis 2 (the matching of the privacy review); - (E) where it runs and what is stored. The engine applies it (
execute(deid=...), thehorae.engine.ports.Deidentifierport,horae.llm.deid.Deidentifierbuilt by the runner and byhorae replayfromhorae.yaml), for a skill with classes and a cloud alias (on by default, no opt-out in v1: answer 7), because the engine is the one place that sees the three paths (a call, a cache hit, a replay). Order: input view → pseudonymize (in a worker thread, within the step'stimeout_s) →LlmRequest(inputpseudonymized,classified,deidentified= the summary) →ModelBackendsrenders (appendsDEID_NOTE: copy placeholders verbatim) → T10 check → send → schema validation → the attempt is recorded inllm[]and its usage spent → re-identify the accepted output and raw intents (the growth is summed first,Pseudonyms.growth: pastMAX_REIDENTIFIED_BYTES, 256 KiB, the step degrades withoutput_too_largeand nothing is substituted; the call and its cost stay recorded) → the permission check, the action guard (decision 46) and routing, all on the re-identified intents and against the real viewed input (guard_for(viewed)): a URL or note link present in the real input matches, and no pseudonym reaches the guard's link and tag rules (they are put back first; an unresolved one is left as the model wrote it and judged as any other text). The mapping lives only in memory:llm[].responseandllm[].intentsare what the provider returned (pseudonymized),llm[].input_hashthe hash of what was sent,llm[].request.deid{version, input_sha256, counts, unresolved}(a digest of what was sent, never one of the mapping or of a value, which could be guessed); the step output and the routed intents carry real values. The LLM cache stores the pseudonymized output (fromllm[]) and the digest of what was sent (deid_input_sha256), re-identified on a hit; the usage ledger holds no data. A reused output (PreviousLlm: a cache hit, or a replay's recorded reuse, whoserequest.deid.input_sha256is kept) is reused only when itsdeid_input_sha256equals this run's de-identified digest (Noneon both sides without de-identification): otherwise a miss, and a replay reports a mismatch ("the de-identified input differs (vocabulary changed…)"). Both checks ofModelBackends(deid_requiredand T10) live inModelBackendsonly: an engine given anotherLlmBackend(a test double, the replay tape) has neither, so the runner always wiresModelBackends. For #29 (claude-cli, PR #105): the subprocess' argv and stdin must be derived only from the decoded frozen body (RenderedRequest.body()), never from theCompletionor the request, so the bytes checked are the bytes sent. As a backstop,ModelBackends.preparerefuses aclassifiedrequest to a cloud alias that was not de-identified (deid_required, an engine given no policy); a policy that cannot de-identify (unreadable vocabulary) degrades the step (deid_unavailable) before anything is sent. Both are not billed; - (F) the cache key (decision 45 G). For a cloud alias, the stored key adds
deid: {version, vocabulary}(DEID_VERSION, the vocabulary file's SHA-256, or"unavailable"), so another vocabulary or transform version is a miss and an entry is only re-identified with the mapping that made it; a local alias' key is unchanged.LLM_KEY_VERSIONis not bumped (the preamble is unchanged;DEID_NOTEis part of a de-identified request only, and those keys changed anyway). Entries of cloud aliases written before #34 are therefore a miss once; - (G) unresolved pseudonyms are left and noted (answer 4): a pseudonym the input
never issued, or a mangled one (
Person 1,PERSON1,[person_1]), stays as the model wrote it and is listed inllm[].request.deid.unresolved(at most 16, 40 characters each); no repair retry. Re-identification puts back the original value's text (_text(value)): a string stays a string, also when it is exactly one pseudonym of a number (a phone given as a number comes back as"33612345678"), so the validated output keeps its types (finding 5); - (H) no secret in a request (T10, the #14 addition).
ModelBackends.sendscans the exact frozen body (RenderedRequest.body()) with the process registry (horae.secrets.redact.current()), primed once with every secret the instance declares (ModelBackends.redaction_names=Instance.redaction_names(), the #53 set:secrets.refs, the lockfile's plugin secrets, the aliases'secret), not only those this process resolved: the raw bytes and the decoded JSON (strings, object keys, whole numbers), every encoding of decision 43. For every backend, local ones too (a secret in a request is never legitimate, and a local endpoint may log it). A match raisessecret_in_requestnaming the secrets (never a value; the log line gives only their count) before the provider backend is called: nothing is sent, the usage ledger releases the reservation (NOT_BILLED, decision 41), the step isdegradedand the engine records asecret_in_requestviolation (run record v1, a compatible addition toviolations[].kind: answer 6); - (I) after the privacy review (provisional, pending maintainer review). The
maintainer's answers on PR #98 stand (1: explicit
local:, never inferred frombase_url; 2: classes in the input view plus a vocabulary insecrets.dir; 3: per run; 4: leave and note; 5: render then send; 6: asecret_in_requestviolation; 7: on by default). Provisional answers to the review's open questions: - A:
localstays explicit and is never inferred;horae doctorwarns when anollamaalias leaveslocalunset and itsbase_urlhost is neither loopback, private, single-label nor a local name (.localhost,.local,.lan,.internal,.home.arpa), or its model tag ends with-cloud; - B: once a skill declares any class, the known-value matcher runs over every
string of the viewed input (not only
free_textfields) and every object key; - C: each name part (at least 3 letters) of a
personvalue or term is a term mapped to the same pseudonym as the whole name (privacy over meaning:[PERSON_1]for "Bob" is put back as "Bob Martin"); - D: an amount's renderings (
1234.56,1234,56,1,234.56,1.234,56,1 234,56,1'234.56, the whole part1234; at least 3 digits, not all zeros) in a string become its bucket label (not reversible, not a pseudonym; counted inamount); object keys under a token-class field become pseudonyms (and are put back by re-identification); - E: bucket bounds written by the skill are accepted as they are (skills are trusted code, reviewed with their plugin): a skill could choose narrow buckets that reveal an amount, as it could simply not classify the field;
- F: the T10 check scans every secret the instance declares (the primed #53 registry), not only the ones this process resolved (see H);
- G:
input_hash(the engine's cache key, decision 47 E) stays an unsalted SHA-256 of the real viewed input: it is stored locally only (run record, cache), never sent, and a salt would break replay and the cache across processes; a dictionary attack on it needs the store, which holds the real outputs anyway; - (J) amendment: the secret check before de-identification (security review of
PR #110). H scanned only the rendered request, after pseudonymization: a classed
value or an amount rendering inside a secret (secret
sk-live-alice-smith-1234567, classed person "Alice Smith") was rewritten, so the scan of the whole value no longer matched while the rest of the secret was sent (a parser differential). So: - the engine scans the real viewed input (its canonical JSON bytes, every
encoding, and its strings, object keys and whole numbers: the same check as
secrets_in) for every resolved or primed secret before it is pseudonymized, and before the LLM cache is consulted; a match degrades the step withsecret_in_requestand records the same violation (naming the secrets, never a value), nothing is sent and nothing is billed;horae eval(#36, decision 48) runs the same check (horae.engine.secrets_in_viewed) on each case's viewed input, offline and live, before de-identifying: the case is an error (secret_in_request) and nothing is rendered or sent; ModelBackends.sendkeeps its check of the rendered bytes (defence in depth: the prompt, the schema and anything added when rendering);- belt and braces, the pseudonymizer replaces no known value, phone or amount rendering whose span in a scanned string overlaps a resolved secret, so a secret is never sent in part even if the engine's check were bypassed;
- the engine's check sees the process registry, which the runner primes with every
declared secret before a run (#53); a declared secret first resolved by
ModelBackends(an engine used without the runner) is caught by the backend's check; - limits: matching misses nicknames, initials, typos and transliterations, and over-matches a known value that is also a common word; a value of more than 48 tokens is not looked for in text; values in unclassed fields that equal no known value are sent as they are (the input view stays the primary control);
- follow-ups: per-instance pseudonyms by keyed HMAC; NER-assisted detection in
free_text; de-identification of data sent to plugins.
- (A) local or cloud, explicit.
Provisional decisions (#36, pending maintainer review)¶
- Skill evaluation harness: golden cases, recorded responses,
horae eval(#36). Numbering: 46 is #35's, 47 is #34's (de-identification). Two new contracts,schemas/eval-case/v1.json(horae.contracts.evals.EvalCase) andschemas/eval-recorded/v1.json(RecordedResponse), and the rules ofhorae.evalsandhorae.cli_eval:- (A) where the cases live. Next to the skill, in its folder:
skills/<namespace>/<skill>/evals/<case>.yaml(a case name is[a-z0-9][a-z0-9_-]{0,63}, at most 256 cases) andevals/recorded/<backend>/<case>.json(one recording per backend,<backend>one of themodels.<alias>.backendnames). The skill loader ignoresevals/, so the cases do not change the skill's digest. Every eval file is openedO_NOFOLLOW(a link is refused), must be a regular file, and is size-bounded (256 KiB a case, 512 KiB a recording); the folders must be real directories; - (B) a case has
schema_version: 1, the stepinputbefore the input view (plain JSON: a YAML date must be quoted), optionaldescription,targets(the routedpathorurlof each target-bound intent type, which a pipeline'sactentries bind in a run; a note type without one getsEvals/<case>.md),budget(a live call's; default{usd: 0.05, tokens_out: 1024}) andexpect:schema_valid(defaulttrue), the exactoutput(without its reservedintents),assertions(each a JSON pointer, RFC 6901, into{"output": ..., "intents": [...]}with exactly one ofequals,length,contains(a substring, or an array element),not_containsandmatches(decision 64) andexists), the exact rawintentsorintent_countsper type, andguard(pass, the default, orviolationfor a case that proves a hostile output is refused). Equality is canonical JSON equality; - (C) a recording is provider-agnostic (maintainer's preference): the parsed JSON
output as the provider backend returned it (the reserved
intentsincluded), itsusageandstop_reason, the concretemodel, the skill's name, version and digest, and the SHA-256 of what was sent (request: the skill's prompt, the viewed input, the output schema:RenderedRequest.summary's digests). Never the provider's payload, headers or a secret. A recording whose skill digest or version, prompt, input or schema digest differs from the current one is stale: reported (stale: [skill, prompt, input, schema]), a warning, not a failure (the repository's own CI test refuses stale fixtures); - (D) offline is the run's path, minus routing.
horae eval <skill>: the input view (Skill.view), the request rendered by the real provider backend of the alias (ModelBackends.render: prompt, viewed input, schema,max_tokensfrom the budget, its pre-flight), then the recorded result handed back by a provider backend whoserenderis the real one and whosesendreturns the recording, soModelBackends.send's own path runs: the production validator (validate_output, the killable worker; avalidator_unavailableis an error), the intents split off (an invalid output proposes nothing), the redaction. Then the intents' omitted targets are filled fromtargets,validate_intentschecks them against the plugin'spermissions.intentsnarrowed to the skill's, and the action guard (check_intents) runs with the viewed input as what the model was shown and the skill's per-type limits. Without--alias, each recorded backend is evaluated with a synthetic alias (the recorded model, a placeholder secret name and a.invalidendpoint, whichrendernever uses; nothing is resolved or sent);--aliasrenders with that instance alias and only its backend's recordings. A backend without a factory (claude-clitoday) is an error (backend_unavailable). No network, no secret, no cost: CI runs every skill's cases (tests/test_evals.py, overtests/fixtures/pluginsand the built-in plugins); - (E) the skill comes from the instance's installed plugins (
<instance>/plugins, checked againsthorae.lock,plugins_invalid1) or, with--plugin-dir, a plugin folder or a folder of plugins (folders withoutplugin.yamlare skipped; see M); it is loaded as the engine loads it (load_skillwith the plugin'spermissions.intents,skill_invalid1). An unknown skill isunknown_skill(3), a malformed name a usage error (2), an unknown--caseunknown_case(3), an invalid case or recordingeval_invalid(1), a skill without casesno_cases(1); - (F)
--livespends money, explicitly, and records it (D1, review findings 1 to 4). It needs the instance (its alias and secret;--alias, required when the instance has more than one,unknown_alias3). Every case is rendered first and the eval's worst case (the sum ofModelBackends.worst_case, what the usage ledger reserves) is shown on stderr. A cloud alias without aprice(ModelAlias.is_localfalse, decision 47 A) is refused (unpriced_alias, 3) unless--allow-unpriced(D3);--max-usdmust be a finite amount over 0 (usage, 2). The worst case must fit--max-usdand what the instance'sbudgets.dailyhas left today (Store.day_spend), elsebudget_exceeded(3), nothing sent.--max-usdis required unless a dailyusdceiling bounds the eval (atokens_out-only ceiling does not bound the cost: usage, 2). Then--yes, or a confirmation on a terminal (refused:not_confirmed, 3; not a terminal without--yes: usage, 2), then the allowance is read again (it may have changed while the confirmation waited). Each case is sent once (no repair retry: the eval reports validity, it does not repair) with the alias' declared key, through a provider backend that keeps the raw result for--record. A report is written to<state_dir>/evals/<namespace>/<skill>/<UTC timestamp>.json(the--jsondocument, withreportset) and a.txtsummary beside it; - (G)
--record(D2, findings 6 and 12) needs--liveand--plugin-dir(a plugin's own folder: never the instance's installed plugins, whichhorae.lockpins; usage, 2). It replaces the recording of each case whose live answer passes the case (so a case expectingschema_valid: falseorguard: violationrecords the bad answer it proves is caught); any other answer is not written and the case says why (recorded_skipped). The output and stop reason are redacted with the process registry first (decision 43). A recording is written atomically and durably (finding 11):mkstempin the backend folder (O_EXCL, random name, 0600), written,fsynced,chmod0644,os.replaced, then the folderfsynced; a recording that cannot be written is reported on stderr and the eval goes on; - (H) results and exit codes (decision 37). Each case (per backend) is
pass,fail(a check failed) orerror(it could not be evaluated:no_recording,input_invalid,eval_invalid,deid_unavailable,case_failed, a backend or validator error). Exit0every case passed,4some failed,1some could not be evaluated, the report could not be written, or any problem above,2usage,3unknown or refused,70internal,130interrupted.--json:{schema_version, mode, skill, skill_version, skill_digest, plugin, alias, run, cases: [{case, backend, model, status, schema_valid, schema_errors, intents_error, guard (pass | violation | not_run), guard_detail, stale, checks: [{name, ok, message, diff}], usage, worst_case, recorded_diff, recorded_path, recorded_skipped, stop_reason, error}], summary: {cases, passed, failed, errors, stale, usage}, estimate, report, report_error, error}(erroriseval_failed,eval_errorsorinterrupted, elsenull); a command error is{schema_version, error}. The report has its own version,EVAL_REPORT_SCHEMA_VERSION= 1 (finding 14), not the CLI error envelope's. Diffs are unified diffs of indented canonical JSON (sorted keys, ASCII), at most 400 lines; text output escapes untrusted characters (safe). Schema errors and guard details stay content-free (decisions 44 and 46); - (I)
pack-daily-briefships three cases fordaily-brief/rank-and-wordwithanthropicrecordings (synthetic):overdue-first(assertions, one note),tasks-only(exact output, no intent) andinjected-embed(a recorded output that obeyed an injected image embed; the guard must refuse it). The fixture pack satisfies the issue's "used by pack-daily-brief" for now (D7): a realpack-daily-briefrepository adopting the cases is future work. Rendering them foranthropicshowed that the fixture's output schema could not be used for structured output (transform_schemaneeds atypebesideenumandconst): the fixture now declares"type": "string"there, and the loader requires it (D4); - (J) a live eval is a run of its own (D1). Under its own lock
(
<state_dir>/locks/_eval-<sha256 of the pipeline, 16 hex>.lock: another live eval of the skill iseval_busy, 3) the eval opens the store for writing (created when missing, as a run does), abandons a dead eval'srunningrow (recover_pipeline), and, once the gate passed,begin_runs a row of pipelineeval:<skill>(a pipeline name never holds:; a skill name too long for the store's 64 characters keeps its start and ends with a digest). Each case is then sent throughLedgerLlm.complete, like a run'sllmstep: prepared, reserved atomically against the daily ceilings insideBEGIN IMMEDIATE(MIN_OUTPUT_TOKENSfloor; a ceiling another process spent since the pre-flight refuses the case,budget_exceeded, nothing sent), sent, then settled or released; each case is its ownstepof the row.Store.finish_bare_runthen marks the rowok(every case sent) orfailed(interrupted), with the cases' cost; the row never gets a run record. Migration 7 rebuilds therunstable so that a finishedeval:row may have no record (its CHECK allowssubstr(pipeline, 1, 5) = 'eval:').horae runshideseval:*rows unless--all(or--pipeline eval:<skill>);horae usageand the daily ceilings count them like any other pipeline's; - (K) failures midway (finding 5). A case whose sending raises anything but a
cancellation is an error result (
case_failed, the exception's type only) and the next case is sent. Each result is kept as soon as it is known: an interruption (Ctrl-C) or a bug midway still finishes the run row (failed), settles what the ledger can (an interrupted call keeps its reservation,estimated), writes the report of the cases sent (error: interrupted), then exits 130 (or 70). A report that cannot be written is said on stderr and inreport_error, the JSON document is still printed, and the exit code is at least 1; - (L) report files (finding 10). Each folder level under the state directory
(
evals/, the namespace, the skill) is created 0700 and must be a real directory (not a link); the.jsonand.txtare written 0600 to new temporary names (O_CREAT | O_EXCL | O_NOFOLLOW),fsynced, then renamed into place, the.txtfirst and the.jsonlast; an existing report is never replaced; - (M) eval files (findings 7 and 13). Dotfiles (
.DS_Store, editors' swap files, temporary recordings) inevals/,recorded/and the backend folders are skipped. A case file whose name is not a case name, an invalid case and an invalid recording are error results of that case (eval_invalid, the file named), the other cases still run;--casemust be a case name (usage, 2). With--plugin-dir, an invalidplugin.yamlof the folder itself isplugins_invalid(1); in a folder of plugins, a skill no valid manifest provides isplugins_invalidwhen some manifest is invalid (it may be that one's), elseunknown_skill; two plugins providing the skill are refused (plugins_invalid); - (N) the judge shares the engine's rules (D5, findings 8 and 9).
_Replayis kept (offline renders with the real backend and replays the recording), but a case fails (stop_reasoncheck) when the recorded or live stop reason is a refusal or a truncation (horae.llm.backends.UNUSABLE_STOP_REASONS=REFUSAL_STOP_REASONS{refusal, content_filter}|TRUNCATION_STOP_REASONS{max_tokens, model_context_window_exceeded, length, model_length}, shared by the backends). The engine'sfill_target(payload, binds)fills omitted targets (from the case'stargets) andcheck_task_fingerprints(typed, shown)refuses atask.update_statusof a task the model was not shown (intents_error), both used by_Run.proposeand by the eval. A case also fails when its usage is over its budget (usage_within_budget).budget_from: <pipeline>(a case taking a pipeline'sllmstep budget) is not done: a follow-up; - (O) de-identification (decision 47). A classified skill's viewed input is
pseudonymized for a cloud alias before it is rendered (offline and live, with the
instance's policy when an instance is loaded, else the alias' own with no vocabulary),
the request says so (
classified,deidentified), and the output and intents are re-identified before they are judged, as a run does; a vocabulary that cannot be used isdeid_unavailableand nothing is sent. A recording holds what the provider saw (the pseudonymized output), never the real values; offline, the same pseudonymization gives the same request digests (not stale); - D4 (amends decision 39 E): the skill loader requires a
typebesideenum/const; CI renders every fixture and built-in skill through every backend inFACTORIES(render only, never sent,tests/test_evals.py);horae doctorreports a schema a backend's structured output refuses, with the offending JSON pointer, and the Anthropic render's error now carries that pointer and its cause; - follow-ups:
budget_from; a--repairlive mode that exercises the repair retry;horae eval --allover every installed skill; a JSON Schema for the eval report (schemas/eval-report/v1.json); a realpack-daily-briefrepository with its cases.
- (A) where the cases live. Next to the skill, in its folder:
Provisional decisions (#39, pending maintainer review)¶
- The built-in scheduler, external triggers and push monitors (#39). Numbering: 48 is
#36's; #38 and #42 may be adding decisions in parallel, so this number may move when they
merge. Compatible v1 additions to the instance contract (
scheduler.monitors,scheduler.max_concurrent,scheduler.misfire_grace_s), one new runtime dependency (cronsim) and one command (horae serve); no store migration.- A, cron library:
cronsim(>=2.7,<3, pinned inuv.lock). Pure Python, no dependency, typed (py.typed), about 1,200 lines with itsexplainmodule, maintained by the author of Healthchecks.io, where it evaluates every check's schedule, so its daylight-saving behaviour is exercised in production.croniterwas considered: larger, and it went through an end-of-life notice and a change of maintainers; APScheduler is a whole scheduler with its own job store and executors, more than needed (Horae has its run lock and store).cronsimalso validates the fields (horae.config.cron.cron_problem): an expression the contract's shape accepts but that cannot fire (0 0 30 2 *,61 * * * *) is a loader problem attrigger.cron(also inhorae doctor). - B, time zone. A trigger is evaluated in its own
timezone, elsehorae.yamltimezone(decision 13; UTC when neither is set); fire times are stored and reported in UTC. Daylight saving follows Debian cron, ascronsimimplements it: a time in the skipped hour fires once at the first instant after the gap, a time in the repeated hour fires once (its first occurrence), and an expression whose hour field is*fires at every real occurrence (tests/test_scheduler.py, Europe/Paris in March and October). - C, mode.
scheduler.mode(builtinby default) is overridden by theHORAE_SCHEDULERenvironment variable when it is set and not blank:builtinorexternal, matched without regard to case (Externalisexternal), anything else a configuration error (horae serveexits 1,horae doctorreports it). Inexternalmodehorae servefires nothing (an external scheduler runshorae run <pipeline>, which is unaffected by the mode); the process still runs, for the HTTP API of #37. - D, missed runs and overlap. Missed fire times are skipped, never caught up: on
start each pipeline waits for its first fire time after now, and a loop that wakes late
(a suspended host) runs the fire time it waited for once, then the first one after
now. The push monitor is what reports a missed run. A fire time while the pipeline's
previous scheduled run is still running or waiting for a slot, or whose run finds the
per-pipeline
flockheld (a manualhorae run:PipelineLocked; a scheduled run takes the same lock as any run, decision 31), is skipped and recorded: a warning log line and the pipeline'sskipped/last_skip/last_skip_reason(running,locked) in the scheduler state. A skipped fire time pings no monitor and writes no run row (the run in progress pings and records its own). A clock stepped back never fires the same fire time twice (the next one is after both the last one fired and now). - D2, misfire grace. A fire time that would start more than
scheduler.misfire_grace_slate (default 3600, 1 s to 7 days), after a suspended host or while waiting for a slot (D3), is skipped and recorded (last_skip_reason: misfire), not run: a run long after its time is more surprising than a missed one, which the monitor reports. - D3, concurrency. Scheduled runs are serialised by default:
scheduler.max_concurrent(1 to 16, default 1) runs at most at once. A fire time that finds no free slot waits, first in first out (statewaiting), and starts when a run ends, unless it is then past its misfire grace (D2); a stop drops the waiting fire times. Interaction with the apply lock (decision 34): whatevermax_concurrentis, two applies never overlap, since every run's apply holds the instance-wide apply lock and waits for it at mostAPPLY_LOCK_WAIT_S(30 s) before it failsapply_lockedwith nothing applied. Withmax_concurrent: 1scheduled runs never wait on each other's applies (only on a manualhorae runorhorae undo); with more, runs proceed side by side and their applies queue on the lock, so a long apply can make another run failapply_locked. Runs side by side share the store (SQLite in WAL mode, decision 36). - D4, isolation. A pipeline whose next fire time cannot be computed (an unknown time
zone, a date out of range; the loader refuses what it can, but
0 0 29 2 *is valid and rare) logs an error naming the pipeline and the exception's type only, shows nonext_fire, and retries after 1 min, doubling up to 1 h; the other pipelines and the runs in progress carry on. - E, the process:
horae serve. The long-running entry point of a container (the name #37's HTTP API will share: one process). It runshorae.scheduler.Scheduler, whosestate()(SchedulerState:mode,active,started_at,max_concurrent, and per pipelinecron,timezone,next_fire,last_fire,last_outcome,last_run_id,last_ping(ok,failed,skipped,none: no monitor),running,waiting,skipped,last_skip,last_skip_reason;to_dict()is JSON-ready, times as...Z) is what/healthzwill report. The state lives in memory: the skip counts andlast_*fields start afresh on restart (persisting them is a follow-up). Scheduled runs run in the process, exactly ashorae runruns them; a crashed run is logged with its run id andinternal error (<type>), never the exception's message. The instance is loaded once: a change tohorae.yaml, a pipeline or the lock needs a restart.horae servehas no--json(it is a process, not a report;horae cache purgehas none either). The wall clock is re-read at least every 30 s while waiting, so a clock step or a suspend delays a fire time by at most that much. - E2, shutdown. The first SIGTERM or SIGINT stops every loop, drops the fire times
waiting for a slot and cancels the runs in progress; a cancelled run stops as
horae rundoes on SIGTERM (partial record savedfailed; an apply in progress finished first and saved with its real status). The run is then reported with the status it was saved with (status and run id from the saved record, its monitor pinged accordingly: an apply that finished isokandup); a run stopped before any record was saved is recordedcancelled(keeping its run id, if it began) and pings nothing: the monitor's own heartbeat window reports it.horae runfollows the same rule for an interrupted run, and bounds that ping to 2 s. The command then exits 0 (a requested stop is the normal end of a server, unlike an interruptedhorae run). A second signal stops waiting for the reports and pings (each up to 10 s): the runs are still awaited so that their records are saved (bounded by the runner's 5 s grace period, or for an apply by its sink calls'call_timeout_s), then the command exits 128 + that signal (130, 143), so a forced stop is visible. A container should be given at least 20 s to stop (composestop_grace_period: 20s; Docker's default is 10 s), more when applies are long. - F, push monitors.
scheduler.monitors.<pipeline>: {secret, kind}: the push URL is a secret (it carries the monitor's token), resolved like any other (decision 25) and added to the secrets the instance names, so it is primed for redaction (decision 43) and checked byhorae doctor; a monitor for an unknown pipeline is a loader problem.kind: uptime-kuma(default) sets thestatus(up/down),msg(the outcome word) andping(the run's duration in ms) query parameters;kind: healthcheckspings the URL for success and<url>/failfor a failure.upis a runok,noopordegraded(adegradedrun is up, as its exit code is 0); everything else isdown(failed, timeout, lost, crashed, and a run that could not begin: plugins not matching the lock, a store, lock or I/O problem, the error kind as the message). Pinged after every run of the pipeline, scheduled orhorae run, never for a dry run, a locked pipeline, or a run stopped before any record was saved (E2).horae doctorresolves the secret and checks it is a valid push URL with the ping's own validator, never echoing the value. The network rules are the LLM backends' (decisions 24, 40): the URL must be aBackendUrl(https://anywhere,http://only to loopback, private or single-label hosts, re-checked at connect time byLanOnlyNetwork), oneGET, no retry, no redirect,trust_env=False, 10 s for the whole exchange, the body bounded at 64 KiB and unused. A failure (timeout, refused, non-2xx, unresolvable secret, invalid URL) is one warning in Horae's words, never the URL, response or exception message, and never changes the run's outcome or exit code; the--jsondocument ofhorae runis unchanged. - Not done (follow-ups): skipped fire times and the
last_*state are not persisted (lost on restart; a store table would need a migration); no reload of a changed instance without a restart; no catch-up option; no/startping (Healthchecks) to measure durations on the monitor side; the push URL with Uptime Kuma's default query (?status=up&msg=OK&ping=) is redacted as a whole, so the rewritten URL is never logged by design rather than by redaction.
- A, cron library:
Provisional decisions (#42, pending maintainer review)¶
- The plugin SDK: Tasks-safe task titles and fingerprints (#42, review findings).
Numbering: 49 is #39's, on its unmerged branch, so this takes 50. The SDK (
sdk/,horae-sdk) is not a contract of the core, but its escaping is the T02 control (docs/security.md), so its rules are recorded here:- (A) the intent's title is the Tasks-safe form.
horae_sdk.intents.task_createescapes the title (horae_sdk.tasks.escape_title), as the acceptance criterion of #42 asks ("intent builders escape"), and the 500-character cut of theTitlecontract happens after escaping. Sinks writing Tasks syntax still usetasks.task_line/task_line_for, which escape again (idempotent: unchanged). A sink for another target showstasks.plain_text(title), for plain-text display only (renamed fromunescape_title; never fed to a Markdown or Tasks target, and not an exact inverse). Follow-up: escape at the sink only and keep the plain title in the intent (the intent would then carry what the source said, and each sink would escape for its own syntax); - (B) builders are total on the title. A title with nothing printable left after
escaping (only zero-width, bidi, controls or whitespace) becomes
(untitled)(tasks.UNTITLED, escaped), so one hostile item never aborts a wholecollect; - (C) escaping rules. Signifiers become uppercase-hex character references;
Markdown and Obsidian punctuation gets a backslash; every rule that looks back looks
at the last piece written, not the last character read (
\::gave a literal::).::keeps a backslash on its second colon. The second%of%%and=of==become%/=: comments and highlights are Obsidian extensions, not CommonMark, nothing documents that a backslash neutralises them, and a reference leaves no%%/==in the line even for a parser that drops backslashes first (a reference is decoded only when rendering, after the syntax is parsed). Autolinks: the:of a URL scheme (a run ofA-Z a-z 0-9 + . -holding a letter, followed by a non-space) and the.of awww.prefix get a backslash, sohttps://,obsidian://,javascript:andwww.are not autolinked (10:30andRe: xare left alone; a bare e-mail address is not changed). The cut never separates a combining mark, a variation selector or an emoji modifier from its character; it is not a full grapheme segmentation (no dependency for it): a regional-indicator flag may be split; - (D) idempotence trade-offs (no behaviour change): a backslash escape already in the
title and a reference in the SDK's own form (uppercase hex, of a signifier,
%or=) pass through and render as that character; any other reference (&, lowercase hex) has its&escaped and renders literally; - (E) verification.
sdk/tests/test_sdk_tasks.pyports the Tasks plugin's emoji and Dataview field regexes (with the optional U+FE0F), its tag regex and the Obsidian constructs, checks that they see every field of a hostile title and none of its escaped form, and a Hypothesis property over a hostile alphabet checks that no::,%%,==or raw signifier survives. Obsidian itself is not run in CI:sdk/README.md("Manual check in a real vault") is the checklist for a release that changeshorae_sdk.tasks; - (F) fingerprints.
intents.fingerprint(*parts)keeps the readable form (parts joined with:, other characters as-) when it is exact (every part non-empty and inA-Z a-z 0-9 . _ -, at most 128 characters), so clean fingerprints and the recordings using them are stable. Otherwise the readable form is lossy and attacker-collidable (a:b/a-b,Re: x!/Re: x?), so it is cut to 110 characters and followed by::and 16 hex digits of the SHA-256 of the parts as a JSON array. An exact form never holds::, so the two shapes cannot collide.task_create's fingerprint parameter iskey(it shadowed the function); - (G) protocol limits in the SDK. A result with more than 256 intents
(
horae.intents.MAX_INTENTS) or a message overMAX_MESSAGE_BYTESminusMESSAGE_MARGINis refused by the SDK before sending (a tool error, or a sink operation'soutput_too_large), with a plugin-side message; content from the core that is not base64 isoutput_invalid, the kind of the core's own sinks; an undeclared intent type is echoed cut to 40 characters; - (H) the test harness. Record mode (
HORAE_SDK_RECORD=1,record=True) is refused whenCIorGITHUB_ACTIONSis set, names each rewritten file on stderr, writes atomically and never through a symbolic link;replayworks inside a running event loop (areplay,areplay_all);checkrefuses unknownexpectkeys; - (I) release.
release-sdk.ymlrefuses a tag whose commit is not on main (git merge-base --is-ancestor), thepypienvironment must be restricted tosdk-v*tags with required reviewers, and the build backend is pinned (hatchling==1.32.4, bumped by Renovate). PyPI attestations are not produced:uv publish0.13.6 uploads existing.publish.attestationfiles but does not create them (follow-up: a Sigstore signing step). Coverage is gated at 85% for the core (src/horae) and the SDK separately, and the sdist no longer ships the tests (they need the core).
- (A) the intent's title is the Tasks-safe form.
Provisional decisions (#37, pending maintainer review)¶
- The HTTP API:
/healthzand the read-only/runs(#37). Three new runtime dependencies (fastapi,uvicornand an explicitstarlette>=1.9,<2, pinned inuv.lock, all older than the 7-day minimum release age), new options ofhorae serve(--host,--port,--allowed-host), one optional argument ofStore.list_runs(before, a page cursor) and one ofStore.open(immutable, E); no contract change, no store migration.- A, one process, one event loop. The API is a FastAPI application served by
uvicorn's programmatic
Serverinsidehorae serve, in the scheduler's event loop (horae.api):/healthzreads the liveScheduler.state(), and there is one process to supervise. Horae binds the socket itself before anything starts (a port in use or a bad host is a configuration error, exit 1,bind_failed, Horae's message), and uvicorn's own signal handlers, log configuration, access log,Serverheader, proxy-header rewriting and lifespan are off: the redacting log record factory (decision 43) stays in place, and request logging is the proxy's job. FastAPI is imported byhorae serveonly./runsand/runs/{id}are synchronous and run in the shared worker thread pool, so a store read never blocks the scheduler's loop./healthzis asynchronous: its store check runs in a small executor of its own (two threads), so a pool busy with slow/runsrequests never fails the health check and SQLite never runs on the loop; it readsScheduler.state()on the event loop, the scheduler's own, so the snapshot never interleaves with the scheduler changing it (no worker thread reads the scheduler). - B, binding.
--host(HORAE_HOST, default127.0.0.1) and--port(HORAE_PORT, default 8080). The container image setsHORAE_HOST=0.0.0.0so that the reverse proxy (Coolify's Traefik) can reach it on the container network; the port isEXPOSEd, never meant to be published.HORAE_HOST=::listens on IPv6 only (IPV6_V6ONLY), so the image's IPv4 loopbackHEALTHCHECKthen fails: use0.0.0.0or override the check. The API has no authentication of its own: SSO is the proxy's middleware (PLAN §7, #41: only/act/is exempt;/runsand/healthzrequire SSO). It must never be exposed without that proxy. The Docker network is trusted: a neighbour container on it can reach port 8080 directly and send anyHostit likes (the Host check of G2 is a defence against browsers, not against neighbours), so #41's template must put Horae on a network shared only with the proxy. - C,
/healthz.200when the store opens read-only at this Horae's schema version and the scheduler is active (SchedulerState.active) or its mode isexternal;503otherwise (also whilehorae servestops). Body:schema_version(1),status(ok/unavailable),version,store(statusok/error,reasonmissing/schema_too_old/schema_too_new/unreadableornull,schema_version) andscheduler(SchedulerState.to_dict(), decision 49 E). No path, no configuration value beyond the scheduler state, no exception text.horae servecreates and migrates the store once at start, so a new instance is healthy before its first run (a failure there is a warning;/healthzthen sayserror). The body stays this detailed (pipelines, cron expressions, fire times, outcomes): it is behind SSO (#41), and keeping neighbours off the network is #41's job (B), so a reduced unauthenticated body is not needed. Behind the SSO proxy an external monitor needs its own way in (a proxy rule for the monitor, or Uptime Kuma on the same network): an operator choice, not Horae's (#41). - D,
/runs.GET /runslists runs newest first (start time, then id) ashorae runs --jsonshows them (horae.run_view.run_json, shared with the CLI: id, pipeline, status,stale, dry run, abandoned, times, duration, cost, error; never the run record,pidorhost). Keyset pagination:limit(1 to 100, default 20) and an opaquecursor(next_cursorof the previous page,nullon the last), stable while runs are added (a new run never shifts a page, unlike an offset); runs that share a start time stay in id order across pages, and a cursor is a position, so it still works when its run has been pruned. Only the exact cursor shape the API writes is accepted (canonical base64url of[<UTC isoformat time>, <run id>]); anything else, a time that would overflow included, is400, never500. Filterspipelineandstatus, which takes the same values ashorae runs --status(run_view.RunStatusFilter:running,ok,noop,degraded,failed,undone;staleis a flag computed from the locks after the query, not a status, in either); live skill evals (eval:<skill>) only withall=trueor their ownpipeline, as in the CLI.GET /runs/{id}is one run, the same object (404when unknown); it stays (a link to one run is what the dashboard and #38's messages need). Bad parameters are400 invalid_requestnaming the parameter, never echoing its value. OnlyGETroutes exist (405otherwise); no slash redirect (/runs/is404). - E, read-only store access. Each request opens the store with
Store.open(read_only=True, immutable=False)(decision 36): no migration, no WAL switch,query_only, and always plainmode=ro, a WAL reader with SQLite's locks and the shared-shm. The CLI's one-shot reads (horae runs) keepimmutable=True, which opens the databaseimmutablewhen there is no-walfile and so creates nothing. The API cannot: it reads in the scheduler's process, where a run's store writes and, on close, checkpoints into the main file at any moment, and animmutableconnection takes no lock and trusts the file not to change, so such a read could be torn (the size of the WAL is no bound: a closing writer checkpoints whatever it holds). With plainmode=roa reader never blocks the writes and sees only committed data, tested with a write transaction open and with a writer thread that checkpoints on every close while the API reads. The cost: a read with no writer active may leave an empty-waland a 32 KiB-shm(the database file's permissions, no data); the next writer's close removes them (tested). - F, no secrets in responses. Every body, errors included, is redacted as data
(
scrub_data: strings, keys, numbers) and then as text with the process registry (decision 43), whichhorae serveprimes with every secret the instance names; the store already redacts what it writes, so this is the second line. Error bodies are Horae's ({schema_version, error: {kind, message}}): an internal error shows its exception type only, a validation error the parameter's name only. - G, headers and surface. Every response from the app:
Cache-Control: no-store,X-Content-Type-Options: nosniff,Content-Security-Policy: default-src 'none'; frame-ancestors 'none',Referrer-Policy: no-referrer,X-Frame-Options: DENY,Content-Type: application/json(uvicorn's own400for a request it cannot parse never reaches the app and has none). No CORS (noAccess-Control-*header; a preflight is405). The OpenAPI document and the docs pages are disabled, on every interface (not only off loopback): the API is three routes, documented here and in the README, and a schema endpoint would be one more thing to keep behind SSO. - G2, Host check (DNS rebinding; added after the security review of this branch).
With the default loopback bind, a web page could point its own name at 127.0.0.1 and
read
/runsand/healthzfrom the user's browser (same origin for the page). So a request whoseHostis not an allowed host is refused before any route runs:400,{kind: invalid_host, message: "host not allowed (see HORAE_ALLOWED_HOSTS)"}, the host never echoed, with the security headers. Always allowed:localhost,127.0.0.1,::1(any port; the container'sHEALTHCHECKand a local client). Also allowed: each--allowed-host(HORAE_ALLOWED_HOSTS, space-separated): the proxy's public hostname, which Traefik forwards asHost; and the bind address itself when it is not a wildcard. An allowed host is a DNS name (_allowed too: Docker service names) or an IP address, compared exactly after lower-casing and dropping a trailing dot: no wildcard, no port, no sub-domain matching (a bad value is a usage error, exit 2). A missing, malformed or repeatedHostis refused. A wrongHostis visible, not refused at start: the loopbackHEALTHCHECKstays green while every proxied request is refused, sohorae servelogs a warning at start when it listens on a wildcard (0.0.0.0,::) with no allowed host, namingHORAE_ALLOWED_HOSTS, and logs each refusedHostvalue once (warning,horae.api;ascii()-escaped so no control or bidi character reaches the log, truncated to 64 characters, at most 32 distinct values then one line saying it stops, through the redacting record factory). It warns rather than refuses to start: a wildcard bind with loopback clients only is a valid setup. Allowed hosts are set on the command line (and the environment) only, not inhorae.yaml: it is a property of the deployment, like--host, and needs no contract change; anapi.allowed_hostskey is a follow-up if instance repos want it. - H, shutdown. The first SIGTERM / SIGINT stops the scheduler (decision 49 E2) and asks the server to stop: it closes its socket and waits up to 5 s for requests in progress. The command exits 0 once both have stopped; a second signal also forces the server. A server that ends on its own stops the scheduler and exits 70.
- I, container. The image's default command is
horae serve(it was--help; it staysserve), and itsHEALTHCHECKasks/healthzover loopback with the standard library (python -c,urllib, no proxy): no curl or wget in the image. The check followsHORAE_PORT, not a--portflag: change the port withHORAE_PORT(aserve --port Ncommand leaves the check asking 8080 and the container unhealthy). A container running another command (init,doctor,run) reports unhealthy, which is harmless for a one-off; one withHORAE_HOSTset to::or to a non-loopback address other than0.0.0.0must override the check.scripts/smoke-image.shchecks thathorae servebecomes healthy with the image's own check, serves/runs, warns aboutHORAE_ALLOWED_HOSTSand exits 0 ondocker stop; under emulation (QEMU) it waits longer (SMOKE_SERVE_WAIT_S,SMOKE_PROBE_TIMEOUT_S,SMOKE_STOP_S). - J, dependencies.
starletteis a direct dependency with its own range (>=1.9,<2): the API relies on Starlette's handler behaviour (exception handlers, middleware order,redirect_slashes), so a change of major version must be a deliberate bump, not a side effect of a FastAPI update. - Not done (follow-ups):
/act(#38),api.allowed_hostsinhorae.yaml; no ETag or conditional requests; no metrics endpoint. Done in #41: the SSO-exemption test against the rendered templates (tests/test_deploy_templates.py, docs/security.md T15) and the network of B: plain compose, one shared only with Traefik; the Coolify template, the resource's own network, which Coolify connects the proxy to and no other app joins (never a sharedtraefik-network; docs/operations/coolify.md, "The network").
- A, one process, one event loop. The API is a FastAPI application served by
uvicorn's programmatic
Provisional decisions (#122, pending maintainer review)¶
task.createtakes an optionallink(#122). A compatible v1 addition: one optional field oftask.create(TaskCreate.link, theTaskLinktype), mirrored inintent/v1.jsonandrun-record/v1.json, and an optionallink_prefixparameter on amode: tasksactentry; no store migration. It lets a task created from an external item (a pull request, a calendar event) carry a clickable link, which the escaped title never can (decision 50).- A, the shape:
https://only.^https://[^F/?#@\\%\[\]]+([/?#][^F\\]*)?$, at most 2048 characters, whereF(TASK_LINK_FORBIDDEN, written as\uescapes) is every Basic Multilingual Plane character of the Unicode categoriesCc,Cf,Zs,ZlandZp: thenotify.pushlink (decision 7) restricted tohttps, with a non-empty authority that holds no@(no user info, so nohttps://good@evilreading asgood),%or brackets, and no backslash anywhere (browsers read\as/in anhttpsURL). No control, format (bidi, zero-width, soft hyphen), space or separator character may appear anywhere, nor a lone surrogate: the model (_check_task_link) and the SDK also check the categories withunicodedata, which covers the supplementary planes (tag characters) that one ECMA-262, Rust and Python pattern cannot. The host is a name, never an IP literal: bracketed IPv6 fails the pattern, and a host whose last label (one trailing dot dropped, after NFKC) is decimal digits or0xhex is what a browser reads as IPv4 (127.0.0.1,127.1,0x7f.1,2130706433, full-width digits), refused by the model and the SDK (the use case is a named web host; alink_prefixon an IP is refused the same way). The SDK keeps a copy of the pattern, and a shared test checks it equals the core's and that both refuse every code point of those categories. Noobsidian://, unlikenotify.push: a notification link opens the vault from a phone, while a task link is written into a note, where anobsidian://URI is an action (new,openwith a command plugin) one click away, and the use case (an external item) is a web page.http://,javascript:,data:and every other scheme are refused by the schema. Loosening it later (another scheme) is compatible. - B, routing binds it (decision 30). A
task.createwith alinkis taken only by amode: tasksentry with a trustedlink_prefixthe link falls under, by the same rule and the same code asnotify.push(_check_link_prefix,_link_under: anhttps://prefix with a host, no user info, query or fragment and a clean path ending in/; same scheme, the same authority, a clean rest of path, own query and fragment allowed). The authority of anhttpslink and prefix is compared as a DNS origin: the host case-insensitively, one trailing dot ignored, an explicit:443equal to no port, and no user info (GitHub.com,github.com:443andgithub.com.fall underhttps://github.com/my-org/); the path stays case-sensitive (/My-Org/is not under/my-org/), as do anobsidian://netloc (compared exactly) and the rest of the rule._link_underis shared, so this applies tonotify.pushhttpslinks too (decision 30 compared the netloc exactly; it only accepts more spellings of the same origin). When atasksentry would take the task but for its link, theintent_unroutedmessage saystask link not under a trusted link_prefix(a fixed text, no URL). Withoutlink_prefix, a task with a link is never routed (intent_unrouted), as fornotify.push: deny by default, so a pipeline names the hosts its tasks may point at (link_prefix: https://github.com/my-org/). A task without a link needs no prefix, so existing pipelines are unchanged. Anobsidian://or otherwise invalidlink_prefixon atasksentry, or alink_prefixon anactentry of any othermode, isparams_invalid(it used to be inert metadata there; no pipeline used it). Upgrading a source: once a source (or skill) sendslink, everymode: tasksentry that receives its tasks needs alink_prefixcovering those links, or the step fails at run time withintent_unrouted(horae doctordoes not inspectactentries, and cannot know what a source will send). The entry's parameters,link_prefixincluded, are recorded in theactstep's output and passed to the sink plugin as theparamsof its apply call (SinkCall.params), as for every entry parameter: a Tasks sink must accept, and may ignore,link_prefix. - C, the action guard. A
task.createlinkproposed by an LLM skill must be exactly a URL of the viewed input, like anotify.pushlink (decision 46), on top of the prefix; a refusal degrades the step. Source and transform proposals are not guarded (first-party plugins, #52), so the prefix is what binds them. - D, no v2. The field is optional and
additionalProperties: falseonly ever refused it: every v1 intent, run record and pipeline stays valid, and a v1 consumer that does not know the field never receives it unless a pipeline opts in withlink_prefix(an applier built before this change would ignore it). Per "Versioning", that is a compatible addition inv1. - E, the sink renders it inert. The intent keeps the link exactly as proposed (routing
and the guard compare it as written).
horae_sdk.tasks.task_line(andtask_line_for) writes it right after the escaped title and before the date fields, as[link](<destination>): a fixed label, never text from the title or the URL; the title cannot open, close or fake a link (its brackets and parentheses are escaped, decision 50).link_destinationpercent-encodes (UTF-8) everything outsideA-Z a-z 0-9 - . _ ~ : / ? # @ ! & ' * + , ; = %: so( ) [ ] < >, backtick,$,",{ } | ^and every non-ASCII character (no signifier, bidi or zero-width character reaches the line); a%that starts no escape becomes%25(no%%); the&of an HTML entity becomes%26(Markdown decodes entities in a destination, and..would otherwise become..after routing checked the path); the second:of::and=of==become%3A/%3D(no Dataview field, no highlight). It is idempotent and percent-decodes to the same string as the link does. The ported Tasks and Dataview regexes see no field in the link and the escaped title (property tests over a hostile alphabet and arbitrary text). A destination longer than 4096 characters is left out (MAX_DESTINATION): a non-ASCII character takes up to 12 once encoded, so a 2048-character link could reach about 24 KiB, past plugin-obsidian's 16 KiB analysis cap for a line; the line is then written without the link, and nothing of it is returned or logged. The core's dry-run diff shows the link as plain text in angle brackets ((link <url>), terminal-escaped), so a)in the URL cannot read as the end of the parenthesis. - F, the SDK.
intents.task_create(..., link=None)checks the same shape (tasks.is_task_link);horae-sdkgoes to 0.2.0 for the link, then 0.3.0 for the reminder order and the block id (decision 53; not yet published; there is no changelog file, the README's "Task links" section and these decisions are the notes). - Order and block id (#127, decision 53). The link comes first, then the
⏰ HH:MMreminder, then the Tasks date fields, so a trailing⏰cannot hide📅(a line written as📅 d ⏰ tby SDK 0.2.0 is read but not rewritten); with a fingerprint the line ends with the^h-block id, which a sink's index must treat as collidable (48 bits) and fail closed on. - Not done (follow-ups): the Obsidian plugin's own Tasks writer must render the link
the same way (
link_destination) before it may listtask.createlinks as supported;task.update_statustakes no link.
- A, the shape:
Provisional decisions (#127, pending maintainer review)¶
- The SDK writes the reminder before the Tasks fields, and a block id (#127). This
number is provisional and may be renumbered against other open PRs.
- A, the order.
horae_sdk.tasks.task_linewrites- [ ] <title> ⏰ HH:MM 📅 date(SDK 0.3.0), where 0.2.0 wrote📅 date ⏰ HH:MM. Tasks reads fields from the end of the line and stops at a signifier it does not know; a trailing⏰hid the due date from it. Readers must accept both orders (plugin-obsidian's parser does). - B, old lines are not rewritten (decision). Lines written in the old order keep it; their due date stays invisible to Tasks until the line is edited.
- C, the block id. With
fingerprint(task_line_for(..., block_id=True)), the line ends with^h-and 12 hex digits of the SHA-256 of the fingerprint. The prefix makes it unlikely to collide with a user's block ids. 48 bits can collide between two fingerprints (about 2e-5 at 100,000 tasks): a sink's block-id to fingerprint index must detect a second fingerprint mapping to the same id and fail closed (refuse) rather than overwrite. A non-string or invalid fingerprint is aValueError. - D, the SDK version.
horae-sdkis 0.3.0.
- A, the order.
Decisions (#38, design note and maintainer answers on #115)¶
- Signed single-use action links,
/act/<token>(#38, the design note docs/design/0038-act-links.md and the maintainer's answers on PR #115: all ten recommendations accepted). A compatible v1 addition to the intent contract (notify.push.actions) and tohorae.yaml(http), store migration 8, one core secret (HORAE_ACT_KEY), two routes. A tap on a notification button changes one task in one predefined way, once, within 24 h, without SSO: the token is the only credential.- A, what a link can do. A closed set of kinds, never an intent document:
task.done(task.update_status {status: done}) andtask.snooze({status: snoozed, until},untilcomputed by the core when the button is pressed:1h,3h, ortomorrowat 09:00 in the instance time zone).notify.push,http.postandnote.*can never be reached. Adding a kind is a core change (ADR 0002). - B, the contract.
notify.pushgains an optionalactions: 1 to 3 (ntfy's limit){kind, task, duration?, label?};taska fingerprint,durationrequired fortask.snoozeand only there. The proposer never writes a URL, nor the button's text:labelis deprecated and ignored (still accepted, one line of at most 64 characters, so proposals written with it stay valid; review decision 2 on PR #115): the core labels each button from its kind and duration (horae.api.act.BUTTON_LABELS:Done,Snooze 1h,Snooze 3h,Tomorrow), so a button cannot say something other than what its link does. Like atask.update_statustarget, every button'staskmust appear in the data the run collected (rule 4 ofhorae.engine.executor, maintainer decision 2), and the action guard scans the labels of an LLM proposal. A notification withoutactionskeeps thededupe_keyit had before the field existed (the field is left out of the key when absent), so an upgrade re-sends nothing. - C, minting. Only the core holds the key. When the apply phase sends a
notify.pushwithactions,horae.api.act.LinkMintermints one link per action whose task is in the store's task index and open (an unknown,doneorcancelledtask's button is left out; so is atask.donebutton for a recurring task, a snooze stays allowed, review decision 3: whether a task repeats comes from the index'srecurringflag and from the run's collected data, any object with a booleanrecurringnaming the fingerprint infingerprint,source_fingerprint,taskorkey, e.g.obsidian.open_tasks, which also updates the flag) and passes them to the notifier with the call:SinkCall.actions, sent to an MCP notifier's<ns>.applyasactions: [{"action": "http", "label", "url", "method": "POST"}](ntfyhttpactions, so plugin-ntfy#4 can forward them as they are;horae_sdk.ApplyRequest.actionsin the SDK), only when there are some. A notifier renders these, never the intent's ownactions, and treats each URL as a credential (sent to the push service only, never logged). The URL ishttp.public_url+/act/+ the token: the base comes fromhorae.yamlonly, never from a request'sHostorX-Forwarded-Host(normalised: a:443inhttp.public_urlis dropped, as a browser'sOrigindrops it). Without the key,http.public_urlor a route (F) whose plugin may applytask.update_status(the runner checksroute_permittedashorae servedoes), nothing is minted and the notification is sent without buttons (logged once per process). Daily-note links are a follow-up (maintainer decision 3). - D, the token (
horae.api.act._token, maintainer decision 4: a signed payload, not a server-side row). One base64url segment without padding,payload || tag:ver(1) kid(4) kind(1) exp(8, Unix s, big-endian) nonce(16) state(8) dur(1) fp_len(1) fingerprint(1..128),tag = HMAC-SHA256(key, "horae-act/v1\0" || payload)(32 bytes, not truncated); 73 to 200 bytes, 98 to 267 characters (^[A-Za-z0-9_-]{98,267}$).stateis the first 8 bytes of SHA-256 over the task's(status, due, snoozed_until)at mint time (maintainer decision 10). It carries no secret, URL or title; it is signed, not encrypted (whoever sees the link can read the fingerprint). Decoding is strict and total: one spelling per token (re-encoding must give the same string), the tag checked withhmac.compare_digestbefore any field, then the version, key id, a known kind, a duration that fits it, the fingerprint's length and alphabet; a string that is not even well-formed pays for one MAC over a buffer of the maximum payload size, so the work barely depends on which check failed (best effort: the store lookups after the MAC still differ). - E, the key (maintainer decision 8). A dedicated secret,
HORAE_ACT_KEY, at least 32 bytes (openssl rand -base64 48), read bySecretResolver.resolve_core: the file<secrets.dir>/HORAE_ACT_KEY, else the environment variable of that name.HORAE_*is reserved for the core (SecretName), so nosecrets.refsentry, plugin or child environment can name it; it is remembered for redaction like every secret and primed byInstance.prime_redaction. Key idHMAC-SHA256(key, "horae-act/kid")[:4]. One key at a time, no grace window: rotating it (new value, restart) refuses every outstanding token. Missing:/actanswers 503 and notifications go out without buttons. Set but unusable (shorter than 32 bytes, unreadable):horae serverefuses to start (config_invalid) andhorae doctorreports an error; set withouthttp.public_urlor a route,horae doctorwarns; read from the environment rather than the file,horae doctorwarns too (a same-uid plugin can read the core's environment through/proc: prefer the file). Nosecrets.refsenv/fileand nodeidentification.vocabularymay name a core secret's variable or file (CORE_SECRETS, any case: the contract refuses it), so no reference can hand the key to a plugin. - F, the route. The change is applied by the instance's one
mode: tasksactentry (its tool and parameters as written; one with a template is not used), as decision 30 routes atask.update_status; zero or several distinct entries, or a plugin that may not applytask.update_status(checked byhorae servewith the plugin registry): no route,/actis 503. EachPOSTopens the instance's sinks (the plugin host) for that call. - G, single use (store migration 8, maintainer decision 7). Table
act_consumed(nonceprimary key,kid,expires_at,consumed_at,run_id,outcome:pending,applied,not_changed,stale,failed).POST: verify; take the apply lock (decision 34 D6, at most 3 s, else 503 and the token stays usable) and the_actpipeline lock, recovering an_actrun a dead process leftrunning; refuse a used token or an unknown task (404, nothing written); open the sinks (unreachable: 503, nothing written); begin a run of the reserved pipeline_act; if the task's state is not the token's, consume itstale(nothing applied, the runfailedwithtarget_changed); else, in one transaction, insert the nonce (pending; a primary-key conflict means used) and journal thetask.update_statusthe core built (never from the request), commit, thenSink.apply(bounded byplugin_defaults.call_timeout_s), then mark the entry applied and the outcomeapplied, update the task index and end the runok. A sink that answers it changed nothing (details.changed: false; plugin-obsidian answers so, withdetails.recurring, for a recurring task askeddone): the entry is marked applied (the sink answered), the outcome isnot_changed, the task index is not updated (adetails.recurringflags the task recurring) and the run endsnoop(review decision 3); the apply phase of a run leaves the index alone the same way. A sink failure or timeout uses the token up (failed, single attempt). A crash after the commit leaves the token used and the change journalled "maybe applied": at most once, never twice._actruns are bare rows (no run record:PipelineNameforbids_and they have no definition or steps; the runs table's CHECK now allows them, likeeval:rows), visible inhorae runs; their journal entry names the task and the sink, theiract_consumedrow the outcome (therefof the logs is SHA-256 of its nonce). Used-token rows are kept 24 h 05 min (MAX_AHEAD_S=ACT_RETENTION_S) after their token expired, so a clock stepped back by less than that cannot make a used token usable again; then they are deleted (one boundedDELETEperPOST, and byprune_runs). - H, expiry and clocks.
exp = mint + 24 h, refused whennow >= exp, and refused whenexp > now + 24 h 05 min(a clock that jumped forward at mint, or a bug). Minting and checking share a host and a clock: no skew leeway. - I, staleness.
POSTrecomputesstatefrom the task index; any change of status, due date or snooze (task done meanwhile, snoozed again, due date moved) makes the link stale (409, consumed). A re-collection that leaves the three fields unchanged (a new title) does not. The task index is now kept by the apply phase (horae.apply.index_task, needed for this decision: nothing wrote it before): an appliedtask.createinserts its task (todo), or updates the title, due date, time and source of a known one without reopening it; an appliedtask.update_statuschanges a known task (a dateuntilin the instance time zone), unless the sink answeredchanged: false; a store failure there is logged and never fails the apply. Migration 8 addstasks.recurring(0 or 1, default 0). - J,
GETshows,POSTapplies (maintainer decisions 1 and 5).GETverifies and reads the store read-only: it writes nothing (no nonce, run, lock or log line with the token), so link previews, prefetchers and scanners leave the token usable; it shows the action and the task's title (escaped, at most 120 characters) and due date, nothing else (never the fingerprint, note or time), with one<form method="post">button, or "task changed" (409, no button).HEADis 405. A ntfyhttpbuttonPOSTs in one tap (the native client sends noOrigin); aviewlink opens the page. Origin check onPOST: anOriginheader, when present, must behttp.public_url's origin (one header only;nullis refused), andSec-Fetch-Site, when present, must besame-originornone; otherwise the 404 page, nothing consumed. The confirmation page hasReferrer-Policy: strict-origin(review finding 1): underno-referrera browser sendsOrigin: nullwith the form'sPOST, so its button was refused;strict-originsends only the origin, never the path, so the token does not leave in aReferer(tested by submitting the rendered form as a browser does). No cookie is set or read. Every/actresponse:Content-Security-Policy: default-src 'none'; style-src 'sha256-<inline style>'; form-action 'self'; frame-ancestors 'none'; base-uri 'none',Cache-Control: no-store,Referrer-Policy: no-referrer(the confirmation page:strict-origin),X-Content-Type-Options: nosniff,X-Robots-Tag: noindex, nofollow,X-Frame-Options: DENY; no script, external asset or Open Graph tag. - K, failures. Every refusal of a token (malformed, truncated, oversized, forged,
another key, expired, too far ahead, used, unknown task, a cross-origin
POST, and any other path under/act) is the same 404 page with the same headers. Distinct answers only where they say nothing about the token: 429 (rate limit), 503 (no key, no route, apply lock busy, sinks unreachable). After a consume the holder of a valid token gets the outcome: 200 applied, 200 "Not changed" (not_changed; "tick it in Obsidian" for a recurring task), 409 stale, 502 failed (after a timeout: the change "may not have been applied"), 500 when something failed after the consume (the page says the change may have been applied, never "not available"). - L, rate limit (maintainer decision 9, review decision 4; constants). In process, for
GETandPOST: a token bucket per client (10 a minute, burst 5), taken before any decoding or store access, and a global one (60 a minute, burst 60), taken only for a token whose MAC verified (checked before any store access, a few microseconds), so invalid tokens never block valid ones; 429 withRetry-After. A request whose token is refused costs its client 3 in all (the client's bucket may go into debt down to minus its burst); the global bucket never goes into debt. A client is an IPv4 address or the /64 of an IPv6 address (rotating addresses inside a /64 gets no new bucket). At most 4096 client buckets (LRU). One process (horae serve); several workers would each have their own. The client address is the peer, unless the peer is inhorae.yamlhttp.trusted_proxies: then the right-mostX-Forwarded-Foraddress that is not itself a trusted proxy (a generalisation of the note's "last hop", identical with one proxy; it serves the reference deployment, below). Without trusted proxies the header is ignored. Atrusted_proxiesentry is at least /8 (IPv4) or /32 (IPv6): a wider one (/0above all) would trust any client's header. Reference deployment, Cloudflare tunnel then Traefik (#41): no entry point carrying Horae's routers may trust forwarded headers (forwardedHeaders.trustedIPs,insecure; docs/operations/coolify.md, forwarded headers), so Traefik replacesX-Forwarded-Forwith cloudflared's address and every request shares cloudflared's bucket (still limited, never unlimited).http.trusted_proxiesis for a chain whose proxies may pass the client's address on. - M, routing and SSO (#41 tests the rendered Traefik template). Exactly
/act/{token}(one path segment; no path converter, no mount or prefix router under/act), so%2F,..or a trailing segment can never reach/runsor/healthzthrough the prefix the proxy exempts from SSO; every other 404 under/actis the same page. #41's exemption should match the token's exact shape,PathRegexp(^/act/[A-Za-z0-9_-]{98,267}$), rather thanPathPrefix(/act). The routes read no SSO or forwarded-user header. TheHostcheck of decision 51 G2 still applies:http.public_url's host must be an allowed host (horae servewarns otherwise). - N, logs. No access log (decision 51 A). One line per
/actrequest (horae.api.act):act <method> <kind> <ref> <outcome>,refthe first 8 hex digits of SHA-256(nonce), for a token whose tag verified; an unverified string isact <method> invalid len=<n>. Never the token, the URL or the task. The operator guide (#41) must turn off Traefik's access log for the/actrouter or drop its path: Traefik logs paths before Horae sees them; the token also reaches cloudflared's logs (atdebug) and Cloudflare's own request logs for the zone. - O, imports.
horae.apiloads its names lazily (PEP 562) so the runner can importhorae.api.act(key, token, minting) without loading FastAPI; the routes are loaded byhorae.api._apponly. - P, the review of PR #115 (the maintainer: "go with what's good for the project").
1, the confirmation page's
Referrer-Policy: strict-origin(J); 2, the core labels the buttons (B); 3, recurring tasks andnot_changed(C, G, I); 4, the rate limit's /64 clients and MAC-verified global bucket (L); 5, this decision renumbered from 53 (53 is #127's); 6, no reference to a core secret, andhorae doctor's warning (E); 7, the narrowesttrusted_proxies(L); 8,:443dropped fromhttp.public_url(C); 9, the runner checks the route's plugin (C); 10, the used-token retention (G); 11 and 12, the timeout and after-consume pages (K); 13, no button for a closed task (C). - Not done (follow-ups): rendering
actionsas ntfy buttons (plugin-ntfy#4) and their iOS behaviour (#72, #65); daily-note links (decision 3); the SSO-exemption test against the rendered template and the Traefik access-log setting (#41); an SDK intent builder foractions(the field is plain JSON meanwhile); showing the buttons in the dry-run diff.
- A, what a link can do. A closed set of kinds, never an intent document:
Provisional decisions (#128, pending maintainer review)¶
-
The action guard refuses note structure, and a skill may refuse every link (#128). Numbering: 52 is #122's, 53 #127's, 54 #38's (
/act, PR #115). One compatible addition toskill/v1.json(an optionallinks); no other contract change. The pack-daily-brief review found an obeyed injection could still write live Obsidian constructs into LLM note content; decision 46 is extended:- A, note structure (rule 8 of
horae.engine.guard). In every text field of anote.*intent (content, andnote.append_section'sheading) proposed by an LLM skill, refused: - a task checkbox: a line whose prefix (any whitespace,
>at any depth, list markers-,*,+and ordered markers<digits>./<digits>)with any number of digits, each followed by whitespace, repeatedly) holds at least one list marker and is followed by[, any one character,](- [ ],* [x],+ [/],1. [ ],- []],> > - [ ]in a callout,- - [ ],1234567890. [ ]); a space after]is not required (conservative). This walk is its own, wider than the Tasks plugin's^[\s>]*([-*+]|[0-9]+[.)]) +\[.\]: the CommonMark walker of H2 stops ordered markers at nine digits, which Tasks does not (a security review finding).[x]without a list marker,-[ ]and- [ab]pass. The other rules below are substring searches anywhere in the text, so no prefix, indentation or nesting can hide them; - any Tasks signifier (
SIGNIFIERS, with or without U+FE0F) anywhere, not only on a task line: a copy of the keys ofhorae_sdk.tasks.SIGNIFIERS(the core does not depend on the SDK at run time);sdk/tests/test_sdk_tasks.pychecks they are equal. Known cost: a brief cannot use ✅ or ❌ as decoration; - any
[[(a wikilink, internal ones too: decision 46 H1e let them pass; a note link is a click away from any note of the vault, and embeds![[stay refused by rule 2); - any
::(a Dataview inline field:key:: von a line,[key:: v],(key:: v)); known cost:std::vector,::1; - any
%%(an Obsidian comment, which hides text in reading view); - a horae block marker:
MARKER, the very recogniser ofhorae.apply.notes(horae:(begin|end), any case, any spacing; a test checks the patterns are equal). Before, the guard passedhorae:end daily-briefand apply then failed the whole run (content_has_marker) every day the input held it; now thellmstep degrades (guard_violation) and apply never runs; - a tag (answer to "allow
#tags?": refused). Tags execute nothing, but they put the note into the user's tag searches, DataviewFROM #tagqueries and a Tasks global filter, so an injected#urgentor#todoreaches dashboards the pipeline does not own; a brief needs none. A tag is a#at the start or after a character that is not a letter, digit,_,&(a character reference%),\(an escape) or/(a URL fragment), followed by a body (up to whitespace or one of!@#$%^&*(),.?":{}|<>, the Tasks tag pattern) that is not only ASCII digits:#128,(#42),C#,page#xand a heading# Titlepass;#todo,#2026planand##xdo not. Known cost: a# commentin a code block is refused.
No code exemption (conservative): the rules apply inside inline code and fences too. Tasks reads its fields from the raw line by regex (a backtick does not hide a signifier from it), Dataview's inline-field parsing of code spans is not documented, and an exemption would need a CommonMark-exact code-span parser.
On the source only. Obsidian's metadata cache, Tasks, Dataview and apply read the note as written; a backslash escape (
\[\[,\#,:\:) or a character reference (📅,%%) keeps them from matching (decision 50 relies on the same reading). So these rules run on the text as written, not on the entity-decoded and Markdown-unescaped views of decision 46 (which keep guarding links, embeds and HTML, what a renderer produces). Consequence:horae_sdk.tasks.escape_titleoutput always passes them (a Hypothesis property insdk/tests/test_sdk_tasks.py, also as- <title>and> - <title>lines), so a skill may list escaped titles. The link rules may still refuse an escaped URL not in the input (https\://…reads as a URL once unescaped, decision 46 0b). - B,links: none(a skill option,SkillManifest.links,inputby default). The input allowance (decision 46, 4) lets a URL through when the viewed input holds it, and an attacker writes the input (a task title, a mail). A skill that writes no link sayslinks: none: in itsnote.*text every link is refused, on every view, whatever the input holds: a URL (rule 6:scheme:/…, special schemes,//…,www., so bare URLs and autolinks),]((inline links, also to vault paths),][(reference links) and a line's leading[label]:definition (also behind a[^footnote]:prefix), and a bare email address. A shortcut reference[label]alone is not refused: it links only through a definition already in the note (the user's).notify.pushandtask.createlinkfields keep their own rules (exactly an input URL under a trustedlink_prefix, decisions 30, 52). Detail:… with a link, and the skill allows none in `content`. The option does not join the skill digest (the cache key): the guard runs on every reuse, so a cached output is checked with the current option. The engine passes it fromLoadedSkill.links(a new member of the port) andhorae evalfrom the skill under evaluation. - C, not done (follow-up). A template render transform, so a skill returns structured lines that the core renders and escapes instead of free Markdown (the issue's third proposal), is left for a later issue: these refusals are the floor whatever renders the note. - D, compatibility.linksis optional with a default, so every v1 skill stays valid and behaves as before for links. The note-structure rules are new refusals: a skill whose prompt asks for task checkboxes, tags or wikilinks in a note now degrades its step; tasks belong intask.createintents (escaped by the sink, decision 50). 56. Optional plugin secrets,permissions.optional_secrets(#136). Provisional. A declared secret had to resolve or the plugin did not start, so a plugin with several credentials of which a user needs one (plugin-calendar'sCALENDAR_*, plugin-github's two tokens, a per-entry ntfy token) needed placeholder values. - A, the form. A parallel list,permissions.optional_secrets, besidesecrets, same name rules (SecretName, at most 256, unique), default empty. Chosen oversecrets: [NAME, {name: NAME2, optional: true}]becausesecretsstays a list of names, so every v1 manifest andhorae.lockstays valid and every reader ofsecrets(the lock, the SDK, the redaction priming) keeps meaning "required". It applies to bothplugin.yamlandhorae.lock(onePermissionsmodel). A name in both lists is refused (pydantic only: JSON Schema cannot say it). - B, permissions. An optional secret is a permission like any other:horae.lockmust grant it inoptional_secrets(_exceedscompares both lists; a grant as a required secret does not cover an optional request, and the locked list is the one in force). - C, the host. Required secrets resolve as before (missing:secret_missing, the plugin does not start). An optional secret is resolved at start; if it does not resolve (no file or variable, too short, unreadable: anySecretError) it is simply absent from the child environment, and the plugin reportssecret_missingitself when a call needs it. Both lists are checked against the environment deny list. When the host opens, it resolves optional secrets with the others, so redaction covers those that resolve. - D,horae doctor. Each unresolved optional secret is aninfoproblem (a newseverityvalue, besideerrorandwarning), at the lock'soptional_secretsentry, never failing the check;okis true and the exit code 0. A required one stays an error. A too-short optional secret is also onlyinfo(its message says why). - E, compatibility. Additive: an optional field with a default. Older cores reading a manifest withoptional_secretsrefuse it (additionalProperties: false), as for any new field. - A, note structure (rule 8 of
Provisional decisions (#137, pending maintainer review)¶
notify.pushtakes an optional stablekey(#137). A compatible v1 addition.keyis aFingerprint(^[A-Za-z0-9._:-]{1,128}$).- A, key. Without
keythededupe_keyis unchanged (decision 30): the SHA-256 of pipeline, routing entry,input_hashor run id, intent and occurrence. A pipeline without an LLM step has noinput_hash, so a reminder re-proposed every 5 minutes got a new key each run. Withkey, thededupe_keyis the SHA-256 of (pipeline, routing entry,key, the local date of the run'sstarted_atin the instancetimezone): the text, the input, the run and the occurrence no longer count. The same keyed notification proposed by many runs on one local day is recorded once; the next local day (DST days are 23 or 25 h long, the date is the calendar date in the zone) it is sent again. - B, skipping. Unchanged mechanism:
plan_changes(notified=)marks the keyduplicate(information, not a problem) andapply_changesskips it, without a journal entry, listing it inApplyResult.duplicates. Two keyed notifications with the same key and entry in one run are one send. - C, compatibility.
keyis absent from the identity of a notification without it, so upgrading re-sends nothing.horae_sdk.intents.notify_push(..., key=None)builds it. - Follow-up. plugin-ntfy keeps its own
dedupe: dailyderivation until its callers passkey; obsidian.reminders should setkeyto the reminder's stable id. - Amendment (follow-up to #137): the key is the identity. The date component in A is
dropped. With
key, thededupe_keyis the SHA-256 of (pipeline, routing entry,key) and nothing else, so a lookback that crosses midnight no longer sends a key twice (the run's local date was not the date the key carried). A proposer that wants "once a day" puts the day in the key (obsidian.remindersalready does:rem:...:<date>T<time>,digest:<date>). The instancetimezoneno longer takes part in the key (it is no longer passed toplan_changes). Retention:notificationsrows are never pruned (prune_runskeeps them, see docs/operations/retention-and-backups.md), so a repeat of an old key is never resent; a keyed notification re-sent after an upgrade is possible once, for keys recorded with the old day-scoped hash.
- A, key. Without
Provisional decisions (#138, pending maintainer review)¶
- A repeated
task.createfingerprint is not re-created (#138). No schema change.- A, plan.
plan_changes(known_task=)reads the task index (decision 54): atask.createwhose fingerprint the index knows (or an earlier intent of the same run planned) is aTaskChangewith actionexisting(title, due and time as indexed; shown as unchanged) orupdate(title, due or time differ;beforeis the indexed task). The planner never reopens anything.updateis what the upstream intent says, not a promise: the diff reads "changed upstream; not applied unless the sink rewrites the task", because a sink may keep its line (plugin-obsidian does:changed: false). - B, apply. Unchanged path: the intent still goes to the sink, the authority on the
vault (plugin-obsidian dedupes by
^h-block id and may adopt or dismiss it). The index is updated from its answer: an applied answer updates title, due and time and keeps the status (a ticked task stays ticked);changed: falseleaves the index alone (so anupdatethe sink declines is planned again next run), exceptadopted(and notdismissed), which indexes the task astodoif unknown. - C, compatibility.
TaskChange.actiongainsexistingandupdate; withoutknown_taskeverytask.createstayscreate.
- A, plan.
Provisional decisions (#139, pending maintainer review)¶
horae undoreverts task status changes;Sink.restoretakes an optionalforce(#139). No schema change (the journal'sbeforeandaftercolumns hold the two blobs); the sink operation list gainsrestore_status.- A, what is journalled. A
task.update_statusjournal entry starts not undoable. Itsbeforeis the task index entry it replaces (TaskEntryas JSON; none for a task the index does not know), taken before the sink is called. When the sink's answer saysdetails.changed: true(and the details are JSON of at most 64 KiB) the entry is marked applied with the details as itsafterand becomes undoable, in the same transaction. Any other answer (changed: false, no details, a recurring task) leaves it as before: not undoable, listed byhorae undo. The/actbuttons (decision 54) journal the same way, so a tick from a notification can be undone too. The details are the sink's own data (the secret gate flags a secret in them, likeafter) and go back only to the sink that produced them (its identity is checked,sink_mismatch). - B, the operation.
<ns>.restore_status(details, optionalforce) returns{"restored": bool}; it joinsSINK_OPERATIONS(a plugin may not provide a tool of that name, as for the others). In process, the optionalTaskRestorableSink.restore_status. The sink alone knows how to put the task back; the core never reads the vault. A sink without it (tool_missing, ornot_supportedas the SDK default) leaves the change listed under "Not undoable", exactly as before, and a run with nothing else to undo isnothing_to_undo. - C, order, refusal, index. Status changes are undone first, latest first, then the
notes. A task a later run changed too is
newer_run(undo that run first, or--force). A task edited since the run isSinkError("target_changed")from the sink: the undo is refused (changed, exit 4) with "use --force"; the status changes restored before the refused one stay restored (undo is resumable) and no note was written. #149: this is deliberately not a transaction, and the report says so: a refusal names the tasks restored before it, the text report ends with "Partly undone" (what is restored, what is not, "runhorae undo <run>again"), and--jsongainspartial(additive). Task restores run before note restores, and that stays. The core does not know which file a task line is in (the sink alone does), so it cannot order a task and a note of one file by journal id; a true interleave needs a dry-runrestore_status, which is out of scope. A run that changed a note and a task line of the same file therefore either is refused up front (changed, the file no longer matches what the note change left) or, when the task restore rewrites the file after the note was read, fails the note's compare-and-swap (target_changed, with a hint that a restored task may have edited the note);horae undo --forcerestores the note in both cases and keeps the overwritten bytes in the journal. For each restored change the task index entry is put back in the transaction that marks the journal entry undone: status,snoozed_until,snooze_tz, wake time and the run that last wrote it, exactly as journalled (Store.restore_task_status). A task the index lost is restored in the sink only.horae undo --jsongains ataskslist (additive;schema_versionstays 1). - D,
force.Sink.restore(target, content, *, expected_sha256, force=False)andrestore_status(details, *, force=False)getforce. It is true only when the user passedhorae undo --force: it is a parameter ofundo_run, set by the CLI flag, and nothing a plugin or a note returns (details, errors, note content) can set it. The core sendsforceonly when true (<ns>.restoreand<ns>.restore_statusarguments), so a plugin built before it is called exactly as before; a forcedrestoreto a plugin whose tool refuses the argument (tool_error) is asked again without it, and an in-process sink without the parameter is called without it (the core's own compare-and-swap on the bytes it read still holds, and--forcestill keeps the overwritten bytes in the journal).forcenever lifts the compare-and-swap, the path rules or the vault boundary (sink_mismatch). - E, compatibility. horae-sdk 0.4.0:
Sink.restore(..., force=False)andSink.restore_status(paths, details, force=False)(defaultnot_supported); the SDK passesforceonly when true and the sink's method takes it.file-sink.restoreacceptsforceand ignores it (no owned-block rule of its own; likewise the built-inLocalFileSink.restore). A sink that overridesrestorewith the old signature must addforceto pass mypy, and<ns>.restore_statusis a reserved operation name (a plugin that provides a tool of that name is rejected at load): both are in the SDK README's "Upgrading a sink to 0.4.0". - Follow-up (plugin-obsidian). Its task sink must put the replaced line in
Applied.details(before_line; today only digests, andrestore_statusexpects it from the core's journal, which the core cannot supply: it never sees the line), serve<ns>.restore_status(tasksink.restore_statuswithforce), and honourforceinrestorefor notes edited outside the owned block.
- A, what is journalled. A
Provisional decisions (#135, pending maintainer review)¶
- A
mode: tasksentry takes severallink_prefixvalues; an unroutable task link is skipped, not fatal (#135). A compatible v1 addition: thelink_prefixentry parameter is free-form pipeline data, so onlyrun-record/v1.jsonchanges (a newviolations[].kindvalue,intent_skipped).- A, several prefixes. On a
mode: tasksentry,link_prefixis either one string (unchanged) or a list of 1 to 32 strings. Each is checked exactly as before (_check_link_prefix:https://, a host, no user info, query or fragment, a clean path ending in/). An empty list, more than 32, or any invalid item isparams_invalidnaminglink_prefix. Atask.createlink is taken by the entry if it falls under any of them.notifyentries keep a single string (decision 30). - B, overlap: the longest prefix wins. When two entries take the same link (their
prefixes overlap,
https://github.com/org/andhttps://github.com/org/app/), the entry whose matching prefix is longest takes it. Two entries that match with an identical prefix stayintent_ambiguous. Within one entry, overlap is moot. - C, degrade per item. A
task.createthat atasksentry would take but for its link (no prefix matches, or the entry has none) no longer fails the step withintent_unrouted: that one intent is left out, the others are routed, and the step endsok. The run record gets oneintent_skippedviolation per proposing call: the source, the positions and the fixed texttask link not under a trusted link_prefix(never a link), and the core logs a warning. If every intent of a call is skipped the detail saysskipped all. Every other routing failure (no entry binds the type, an unknown fingerprint, ambiguity) still fails the step. Extended by #149: anotify.pushwith alinkthat anotifyentry would take but for that link (nolink_prefix, or none that the link falls under) is skipped the same way, with the fixed textnotification link not under a trusted link_prefix; a call that proposes both kinds lists both texts in its one violation. Anotify.pushwithout a link, or one that nonotifyentry binds at all, is unchanged.horae doctorreports, as a warning (never an error), each pipeline whose newest 20 runs holdintent_skippedviolations, with the latest run and its detail, so a skipped link does not stay unseen. - D, compatibility. Pipelines that never had an off-prefix link are unchanged; ones
that did now succeed with a violation instead of failing. A consumer must accept the new
kind; per "Versioning" a new enum value is a compatible addition.
- A, several prefixes. On a
Provisional decisions (#43, pending maintainer review)¶
- Marketplace resolution (#43). New schema
marketplace/v1.json(a marketplace'smarketplace.json) and two optionalhorae.yamlkeys,marketplacesandmarketplace_pins. The number may be renumbered against other open PRs.- A, the index contract.
MarketplaceIndex(horae.contracts.marketplace) mirrorsschema/marketplace.schema.jsonofhorae-dev/marketplace, strict andextra=forbid:{plugins: [{name, repo, versions: {<semver>: <40-hex sha>}, tier}]}, names unique. Name, semver andrepo(GitRepoUrl: https only) are the lockfile's types. The index pins a 40-hex SHA-1 or a 64-hex SHA-256, the lockfile'sCommitSha(#153: the schema first took 40-hex only;marketplace/v1.jsonis regenerated, no version bump, as it only accepts more). Unique names are checked by the model, not by JSON Schema (as in the marketplace verifier). - B, config.
marketplaces: an ordered list of 1 to 16https://git URLs, highest priority first, default["https://github.com/horae-dev/marketplace"]; no duplicate.marketplace_pins: plugin name -> one of themarketplaces. - C, fetch and cache.
horae plugin search|resolveclone (shallow,--depth=1, not--filter) or update each index into<state_dir>/marketplaces/<hash of the URL>/repo.git, readmarketplace.jsonfrom the fetchedHEAD(at most 4 MiB), validate it, and store the validated copy and when it was fetched beside the clone. A copy that fails validation never replaces the cache. Git is hardened as the marketplace verifier's_git:protocol.allow=neverand onlyhttps,GIT_CONFIG_GLOBAL/SYSTEMoff, no prompt, an empty environment butPATH,HOME,LANG,TMPDIR, a 120 s timeout,--before the URL. The transport is a constructor argument ofMarketplaceClient, never a setting; only tests passfile, to clone local fixture repositories. - D, resolution.
name[@version]. Indexes are searched inmarketplacesorder. Without a version, the highest semver by semver.org precedence; pre-releases are skipped unless--pre(a version named explicitly may be one; a plugin with only pre-releases is an error that says so). A name listed by several indexes under the same repository (a mirror) comes from the highest-priority one, entirely. Under different repositories it is a conflict: an error that names every index with its repository (priority order) and suggestsmarketplace_pins. Unknown name or version are errors that list where it looked or the available versions. - E, disambiguation: a pin in config. Chosen over an
index-name/pluginsyntax: an index is any git URL and has no short name that is unique (twomarketplacerepositories of different owners are likely), a pin is explicit, reviewable inhorae.yaml, and keepsname@versionthe only reference grammar (also the lockfile's and #44's). A pin to an index that does not list the plugin is an unknown-plugin error. - F, offline. When a refresh fails, the cached copy of that index is used and a warning
names the index, the reason and the copy's date.
--offlineskips the fetch. An index with no cache (fetch failed, or--offline) is an error, never skipped: skipping a higher-priority index could hide a conflict. The cache is validated again when read. - G, CLI.
horae plugin search [QUERY]andhorae plugin resolve NAME[@VERSION](--offline,--pre,--json,-i). Exit 0 ok; 1 configuration problem or no cache; 2 malformed reference; 3 unknown plugin or version, or conflict. They install nothing (#44). - C2, fetch environment, cache and concurrency (#153). The git environment stays
allow-listed; a call that reads a remote (index clone/fetch, plugin
clone,fetch,ls-remote) also inherits exactlyHTTPS_PROXY,HTTP_PROXY,NO_PROXY(and lowercase forms),SSL_CERT_FILEandSSL_CERT_DIR, so a server behind a proxy or with its own CA can fetch. A proxy must be anhttp,https,socks5orsocks5hURL with a host and no credentials; a CA path must be absolute and exist; otherwise the fetch fails with an error that names the variable and never its value (an index then falls back to the cache, as for any failed fetch). Protocol allow-list, noext::, hooks off and the other variables are unchanged with a proxy set. Every directory the client creates under the cache (anduv-cache) is0700, ancestors included; one that already existed is not changed. Each index clone is written under an exclusiveflockon<cache_dir>/<hash>.lock(waiting up to 150 s); past that,LockBusy: exit 5, kindlock_busy, as thehorae.lockguard. - H, trust. An index is untrusted data (security.md, B6): it can only point to a repository and a SHA. #44 re-verifies the tag and the SHA, #46 shows the permissions.
- A, the index contract.
Provisional decisions (#44, pending maintainer review)¶
- Install from git with a pinned commit (#44).
horae plugin add NAME[@VERSION](--offline,--pre,--json,-i) resolves the name as decision 61 D, thenhorae.marketplace.install.PluginInstaller.install(name, version, repo, sha), which a direct install from a git URL (#48) calls the same way, without the marketplace. No schema change.- A, fetch. The marketplace's hardened git runner (decision 61 C), extended for every
call with
core.hooksPath=/dev/nullandGIT_LFS_SKIP_SMUDGE=1.git clone --bare --depth=1 --no-tags --single-branch --no-recurse-submodules --branch v<version> -- <repo>, then onefetch -- <repo> <sha> +refs/tags/v<version>:refs/tags/v<version>, so the tag is the remote's (a branch named like the tag cannot stand in for it). Onlyhttps(GitRepoUrl) is accepted, checked before git runs; the transport is a constructor argument, never a setting (only tests passfile). Theclone,fetchandls-remotecalls inherit the proxy and CA variables of decision 61 C2 and nothing else; an install works in its own scratch directory, so it shares no clone to lock. - B, verify.
rev-parse <sha>^{commit}must be the pinned SHA andrefs/tags/v<version>^{commit}(an annotated tag dereferenced) the same commit, else the install is refused: a moved tag, a tampered index, or a SHA the repository does not have. The tag name isv<version>, as the marketplace's verifier expects. - C, the tree. Before checkout, from
ls-tree: at most 5000 entries and 100 MiB of file content (and at most 200 MiB fetched); no.,.., empty or.gitsegment (any case); no.horae-install.jsonat the root; no symlink whose target is absolute or climbs out of the tree. Checkout of the tree only (no.gitis installed) withcore.symlinks=false(a symlink inside the tree becomes a small file holding its target),core.protectHFS/protectNTFS,--no-recurse-submodules(a submodule stays an empty directory). No hook or filter runs: hooks are off, and a filter needs config, which is/dev/null(global, system) or written by our clone (the repository's is never cloned). - D, manifest.
plugin.yamlat the commit must validate asPluginManifestand name the resolved plugin and version, else refused. - E, where, and atomicity.
<instance>/plugins/<name>, the layout the plugin host already reads (HostRegistry.from_directory), derived from the validated name only. All the work happens inplugins/.install-<random>/, and the finished tree is renamed into place (same file system: atomic), soplugins/<name>is absent or complete, even if the process is killed. A scratch directory is never read by the host; one older than an hour is removed by the next install. A name already installed is refused (upgrade is #47). - F, what is recorded: a manifest in the install directory, not
horae.lock.plugins/<name>/.horae-install.json={schema_version: 1, name, version, repo, commit}, the fields of aLockedPluginwithoutpermissions(Installed.lock_entry(permissions)builds the entry).horae.lockstays the list of approved plugins: writing it is #46, with the permissions the user approves. So an installed plugin is not enabled: the host loads only the plugins ofhorae.lock, and the CLI says so and what is left (approve its permissions, install its dependencies). The record is what #46 and #47 read to know what is on disk. - G, dependencies.
install(..., prepare=...)runs on the verified tree before the rename: the hook for #45 (the plugin's venv); a failure aborts and leaves nothing. - H, CLI exits. 0 installed; 1 a repository that cannot be fetched (
install_failed); 3 refused (install_refused) or already installed (already_installed); the others as decision 61 G.
- A, fetch. The marketplace's hardened git runner (decision 61 C), extended for every
call with
Provisional decisions (#131, pending maintainer review)¶
- The locked network list travels in every plugin call's
_meta(#131). No schema changes: it is a wire addition of the plugin host (horae.plugins.host.session) and the SDK (horae-sdk 0.5.0). Decision 62 is taken by open PR #155.- A, the key. Every request to a plugin (a source, a transform, a sink operation) carries
_meta["horae/network"]: the plugin'spermissions.networkas approved inhorae.lock(the host's effective manifest, never the manifest's declared list), a list of host names in the lock's order. A plugin the lock grants no host sends[]: an empty list is never "everything allowed", and the key is always present from a core that has this decision. The key has nodev.prefix on purpose: it names a core capability a plain MCP server never sets, andhorae/is reserved for the core (the earlier keys,dev.horae/input,dev.horae/pathsanddev.horae/intents, are unchanged). - B, trust. The core builds
_metaitself; a transform's untrusted input travels underdev.horae/inputand parameters are arguments, so neither can set or shadow the key. Before M5 it is advice the plugin enforces on itself, not isolation: a malicious plugin simply ignores it (T05 stays open until the egress proxy, #50). It protects against a configuration that points a good plugin at a host the user did not approve (aserverorallowed_hostsfrom trusted pipeline config, a redirect, a hostile URL). - C, matching.
horae_sdk.Network.allows(url)uses the lock's semantics and nothing looser. A host matches only if it is written exactly as listed: names are lowercase (Hostname) and compared without case folding, trailing dot, wildcard or implicit subdomain; an internationalised name is itsxn--A-label; any port is accepted on an approved host (decision 10). The URL must satisfy the shape ofHttpsUrl:httpsonly, no user info (https://allowed@evil/andhttps://evil\@allowed/never match), no backslash, whitespace, control character, fragment or IP literal. A list entry that is not a validHostnamematches nothing. The core's helperhorae.contracts.url_hoststays the core's reading; the SDK has no dependency on the core, so it carries its own copy, and the SDK tests assert the two agree. - D, compatibility. A core older than this decision sends no key; the SDK then reports
the list as unknown (
allowed_hosts is None,host_allowed(url) is None), which is not "refused": the plugin decides, and falls back to its own configuration. A present but malformed value is read as an empty list (fail closed). An SDK older than 0.5 ignores the key. The list is repeated on every call (a few names), not sent once. - E, scope. Plugins are not changed here:
plugin-ntfy(server) andplugin-calendar(allowed_hosts) are to callcall.host_allowed(url)/request.host_allowed(url)in follow-ups, treatingFalseas a refusal andNoneas "use my own config".
- A, the key. Every request to a plugin (a source, a transform, a sink operation) carries
Provisional decisions (#134, pending maintainer review)¶
- A public replay backend, a request digest of a case, and the
not_contains/matchesassertions (#134). Provisional. Changeseval-case/v1.json(two optional checks; an older case file stays valid, andschema_versionstays 1). Decision 62 is taken by open PR #155 and 63 is merged.- A, the replay backend is public.
horae.llm.replay.ReplayBackend(inner, source)replaces the privatehorae.evals._harness._Replay: itsrenderis the real backend's (same payload, same digests, same cost bound) and itssendreturns a recording, so nothing leaves the host and no secret is read.sourceis oneCompletionResult(what the eval harness uses) orRecordings, a library looked up by request digest.replay_backends(models, source)builds theModelBackendsover it._Replaystays as a subclass ofReplayBackend(same constructor), so the packs that import it keep working; it is deprecated and is removed once the packs have switched. - B,
horae run --llm-replay <recordings>.<recordings>is a recording file, or a folder searched (at most 6 levels, 4096 files, dotfiles and symbolic links skipped) for*.jsonrecordings in the format of decision 48 C, e.g. a skill'sevals/recorded/. Everyllmstep renders its request with the real backend of its alias, and the recording whose request digest (prompt, viewed input, output schema) matches answers it, preferring one recorded for the alias' backend. The answer goes through the same validator, intent split, redaction, routing and guard as a live one. A request no recording answers fails the step withreplay_miss(the run isdegraded, the message names the digests and whether a recording shares the prompt or the schema): never a live call. Two recordings of one request and backend with different outputs are refused when loaded. A recordings path that cannot be read is exit 1,replay_unavailable. The cache lookup is skipped (as--no-cache); an accepted output is cached like any other, so a replay that must leave the cache alone is a--dry-runor a scratch instance. No new instance setting: the flag is the only switch, so a replay can never be configured by mistake into a production instance. - C, the request digest of a case.
horae.evals.request_digest(sue, loaded)returns theRecordedRequest(SHA-256 of the prompt, of the canonical viewed input and of the canonical output schema) thathorae eval --live --recordwould store and that--llm-replaylooks up, rendered offline through the real backend (the digests do not depend on the backend or the model; the skill's input is de-identified as for a cloud alias unless a localbackendis given). It raisesEvalErrorfor a case that cannot be rendered. - D, a stale recording fails
horae eval. Offline, a recording whose request digest (or skill digest) no longer matches is the case errorstale_recording(exit 1), with the messagecase <name>: the recording for backend <b> is stale (<prompt|input|schema| skill> changed since it was recorded); re-record it with horae eval --live --record. Before, it was a warning and the stale answer was still judged. Live, a stale recording stays a note (the new answer is what gets recorded).stalestays in the JSON report. - E,
not_contains. The opposite ofcontains: a string holds no such substring, an array no such element. Something must be there: a missing value fails (nothing there; useexists: falseto assert absence), so a mistyped pointer cannot make the check pass vacuously. A non-string needle on a string fails. - F,
matchesand ReDoS. A regular expression (Pythonresyntax,re.search, unanchored, flags inline such as(?i)) that must be found in the string at the pointer. The core has no user-supplied regex elsewhere; its pattern for untrusted work that can run long is the killable worker of the output validator (horae.llm.validate, decision 44), andmatchesuses it: the pattern is at most 256 characters and must compile (checked when the case loads); the searched string at most 65536 characters (a longer one fails the assertion); the search runs in a short-livedpython -I -Bchild (empty environment,cwd/, new session, CPU and memory ceilings) that is killed after 2 seconds. A search that does not finish fails the assertion (the pattern could not be searched), never passes and never hangs the eval. A non-string value fails. Nothing else changes: the worker imports nothing of Horae. - G, what the packs switch to.
pack-daily-brief'stests/test_pipeline_e2e.py(Recorded) tohorae.llm.replay.ReplayBackendorreplay_backends;scripts/sync_recordings.py(_offline_backends,deidentify,recorded_request,request_for,viewed_input) tohorae.evals.request_digest;pack-remindersuses no private replay. Pipelines can be tested withhorae run --llm-replay.
- A, the replay backend is public.
Provisional decisions (#54, pending maintainer review)¶
- The read-only MCP server (#54). New command
horae mcp serve [-i <instance>] [--brief-pipeline NAME](horae.cli_mcp,horae.mcp_server), over themcpSDK already used by the plugin host (mcp>=2.3,<2.4,MCPServer), stdio only. Decision 64 is taken by #134.- A, tools. Exactly three, none with a side effect:
tasks.today(open tasks, statustodo, due today in the instance's time zone or overdue, overdue first;limit1 to 100, default 50),brief.latest(the latest run of the brief pipeline,daily-briefunless--brief-pipelinesays otherwise, and thenote.*paths it journalled, never their content;run: nullwhen it never ran) andruns.recent(newest first, live skill evals left out as in/runs;limit1 to 50, default 10). The names are the ones of PLAN §3.5.pipeline.runis #55 and is not here; the server has no resource and no prompt. - B, contracts. Each result is a strict pydantic model (
horae.contracts.mcp), exported asschemas/mcp/tasks-today/v1.json,brief-latest/v1.jsonandruns-recent/v1.json(export --checkguards them) and published as the tool'soutputSchema; the client receives it asstructuredContent. A run is the HTTP API's representation (horae.run_view.run_json, decision 51 C), shared, not copied. Caps: 100 tasks, 50 runs, 20 targets; titles 200, targets 256, errors 500 characters. - C, untrusted text. The client is an LLM and a note can say anything. Task
titleandtarget, a target inbrief.latestand a runerrorare markedx-untrustedin the schema, redacted with the process registry, reduced to one printable line (control characters become spaces), clipped, and declared as data in every tool description and in the server'sinstructions. The server never interprets them. Marking reduces, and does not remove, the risk that a hostile title steers a client; the tools cannot act on it. - D, read-only and no network. Each call opens the store
mode=ro(Store.open(read_only=True): no migration, no write, no file created; a missing store is empty), takes no path, command or secret from the client, and closes it. No socket is opened, so there is nothing to authenticate here; token auth for a network transport is #56. A store failure is the fixed tool errorstore_unreadable(no path, no exception text). The tools are annotatedreadOnlyHint,idempotentHint, notdestructiveHint, notopenWorldHint. - E, exit and logging. stdout carries the protocol only; problems go to stderr. Exit 0 when the client closes the connection, 1 configuration problem, 2 usage error, 70 internal error (decision 37).
- A, tools. Exactly three, none with a side effect:
Provisional decisions (#132, pending maintainer review)¶
- Local-network grants in
horae.lock, and how plugins reach the M5 egress proxy (#132).permissions.networkholds public DNS names reached overhttps(decisions 6, 10, 63) and cannot express a service on the user's network: a self-hosted ntfy atntfy.lanoverhttp, Home Assistant athomeassistant.local:8123or192.168.1.10:8123, Proton Mail Bridge at127.0.0.1:1143. Decision 62 is taken by open PR #155; 63 to 65 are merged.- A, a separate grant. New
permissions.network_local(plugin manifest and lock, both schemas regenerated): a unique list ofLocalEndpointstrings,host:port, e.g.["127.0.0.1:1143", "[::1]:1143", "192.168.1.10:8123", "homeassistant.local:8123"]. A string, not{host, port, scheme}: it sorts and diffs like the other lock lists, and the scheme is not part of the grant (below).networkis unchanged and still refuses IP literals,localhostand ports, so nothing that was refused before becomes allowed there. - B, what a local endpoint is. The port is always explicit (1 to 65535, no leading
zero). The host is one of: a lowercase name ending in
.local(mDNS),.lan,.internalor.home.arpawith at least one label before the suffix; an IPv4 literal in 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 or 169.254.0.0/16; or a bracketed IPv6 literal::1, in fc00::/7 (ULA) or fe80::/10 (no zone id). IP literals must be canonical (str(ipaddress.ip_address(...)): no leading zeros, compressed lowercase IPv6, no IPv4-mapped form), so one service has one spelling and exact matching is sound. Never a public address or name,localhost, a single-label name, a wildcard, a scheme or a path. Cloud metadata services are refused even as an explicit grant: the addresses 169.254.169.254, 169.254.170.2, 169.254.170.23, fd00:ec2::254 and fd00:ec2::23, and every name whose first label ismetadataorinstance-data(metadata.google.internal,metadata.internal,instance-data.ec2.internal). The JSON Schema checks the shape (suffixes, private prefixes, port, the metadatanot); the model adds the ranges and the canonical form. CGNAT (100.64.0.0/10, e.g. Tailscale) and single-label Docker service names are left out on purpose: a Docker service gets a.internalalias, and widening is a later, compatible change. - C, plaintext. Plain
httpis allowed only on a local endpoint, never on anetworkhost. The grant names a host and port, not a scheme:httpandhttps(and, foraddress_allowed, any protocol) may use it, since what is approved is reaching that service, and TLS on a LAN is the user's choice.http.postintents,mcp-httpruntimes and task links keepHttpsUrlandnetwork: a local grant is for the plugin's own connections only. - D, approval. Manifest-declared versus lock-approved stays as decision 63: the host
refuses a plugin whose manifest asks for a
network_localentry the lock does not grant (permissions not approved (network_local: ...)), and the lock's list is the one in force. The approval flow (#46) must show these entries apart fromnetwork, under "local network (plain http allowed)", one line per endpoint. Until then a lock is hand-written: the lockfile contract accepts the key, and a lock without local grants is written exactly as before (network_localis left out when empty), so an older core still reads it. - E, the wire. Every plugin call also carries
_meta["horae/network_local"]: the locked list, always present from this core ([]when none). horae-sdk 0.6.0:host_allowed(url)isTruefor anhttpsURL on an approved host (decision 63) or anhttp/httpsURL whose host and port are exactly an approved local endpoint (no port in the URL means 80 forhttp, 443 forhttps);address_allowed(host, port)does the same for other protocols (IMAP);local_endpointsis the list. True / False / None stay: nohorae/networkat all is unknown (None);horae/networkwithouthorae/network_local(a decision-63 core, which could not grant one) means no local endpoint. No normalisation and no DNS: a public name never matches a local grant (ntfy.lan.evil.test,127.0.0.1.nip.io), nor do user info, another spelling of an address or another port. Old plugins and SDKs ignore the new key; an older core sends neither key and the SDK reports unknown. - F, the M5 egress proxy (to be followed by #49 and #50). The proxy is exposed by an
explicit variable, not transparently: in M5 isolation only, the core sets
HORAE_EGRESS_PROXY(anhttp://URL of the allow-listing proxy) in the plugin's clean environment;*_PROXYstays on the deny list (decision 28) and plugins keeptrust_env=False. A plugin sends its connections to public hosts (network) throughHORAE_EGRESS_PROXY(HTTPCONNECT), and connects to local endpoints directly. The plugin container's network has no default route: the proxy, which resolves names itself and refuses private, loopback, link-local and metadata addresses (T07), is the only way out for public hosts, and eachnetwork_localgrant becomes an explicit route or firewall allow rule for exactly that address and port (a local name is resolved once by the core when the container starts, and refused if it resolves outside B's ranges or to a metadata address). Before M5 the variable is unset: a plugin connects directly, as today. A plugin that sees the variable and cannot use a proxy must fail, not bypass it (it could not anyway). Loopback in M5 means the plugin's own container; reaching a service on the Docker host's loopback (Proton Mail Bridge) needs that route to the host (#49/#50 decide how, e.g. a host-gateway route limited to the granted port). - G, limits before M5. A local name can still resolve to a metadata or public
address: the grant checks what is written, not what DNS answers. Refusing that at connect
time is the proxy's and the route's job (#50); a plugin that resolves names itself keeps
refusing a resolved metadata address (plugin-ntfy already does). As in decision 63 B, the
_metalists are advice a good plugin enforces on itself, not isolation (T05). A grant of127.0.0.1:<port>before M5 reaches whatever listens on the core's own loopback (e.g. the HTTP API, decision 51 B): the approval shows it as a local-network grant for the user to judge. - H, plugin follow-ups (not changed here). plugin-imap: declare its Bridge endpoint in
network_local(e.g.127.0.0.1:1143,127.0.0.1:1025for SMTP), require horae-sdk 0.6, and checkcall.address_allowed(host, port)before connecting (Falserefuses,Nonefalls back to its own config); drop the 0.1.0 note that a local Bridge is always refused. plugin-homeassistant: accept an IP-literal or.local/.lanbase URL (httpallowed), check it withcall.host_allowed(url), and documentnetwork_localwith an explicit port instead of refusing IP literals. plugin-ntfy: accept anhttp://serveron a local endpoint throughrequest.host_allowed(url)(port 80 or an explicit one), keephttpsfor public servers and its resolved-address checks, and document thenetwork_localentry.
- A, a separate grant. New
Provisional decisions (#160, pending maintainer review)¶
- An
llmstep can be skipped on an empty input, and a skill can bindtask.createfingerprints to the viewed input (#160). Provisional. Two compatible, opt-in additions: an optionalllm.skip_when_emptyinpipeline/v1.jsonand an optionaltask_fingerprintinskill/v1.json. Neither is in a pipeline or skill that does not write it, and the pipeline digest is unchanged for one that omitsskip_when_empty(nullis left out of the canonical form). Decision 66 is added by PR #159 and 62 by PR #155. Found building plugin-gmail#3 (plugin-gmail PR #5). Atask.createlink built from the fingerprint (item 3 of the issue) is not part of this decision; see F.- A,
skip_when_empty. On anllmstep,true, or a list of 1 to 16 input view paths (ViewPath, the syntax of a skill'sinput_view). It is evaluated on the viewed input (after the skill's view, before de-identification, the cache lookup and any model call).true: the whole viewed input is empty. A list: the values the paths reach are all empty (a path that reaches nothing is empty), so one non-empty listed field runs the step. A list path must lie on the skill's input view (be a prefix of a view path or extend one), else the plan fails withparams_invalid: a path the model is never shown would be empty on every run. - B, what empty means.
null,"",[],{}, and a list or object whose members are all empty in this sense, recursively. Any other string, any number (0too) and any boolean (falsetoo) is not empty. A view that does not match the input at all is stillinput_invalid(a degraded step), not an empty skip. A pipeline whose collect source also returns a label (source: "gmail.triage") is therefore not empty as a whole: list the field that matters ([].data.needs_interpretation), or drop the label from the skill's view. - C, how a skip is recorded. No
llm[]entry (no call was made, so there is no backend, model or usage to state): the step is recorded with statusskipped, no error, andoutput: {"skipped": "empty_input", "skill": "<skill>"}. Later steps run, as after an unchanged-input reuse; askippedstep isokfor the run's status, and a run that proposes no intent at all endsnoop(the same rule as a reuse).RunRecord.input_hashstays unset and nothing is written to the LLM cache (no accepted output exists, and the cache is not even looked up). Cost is zero. A replay re-evaluates the same rule on the same recorded input. - D,
task_fingerprint. A skill may declaretask_fingerprint: {ids: <ViewPath>, prefix: <text>}.idsis aninput_viewpath (or below one) whose string values (or the strings of a list value) are the ids;prefixis 1 to 64 characters of the fingerprint alphabet (A-Z a-z 0-9 . _ : -), e.g.gmail:. Atask.createthe skill proposes must carry a fingerprint equal toprefix+ one of those ids, as exact strings in the viewed input; anything else (an id the input never held, the id without its prefix, a different prefix) refuses the whole batch. The manifest is invalid ifidsis not in the input view or iftask.createis not inintents(pydantic-only rules). Without the rule atask.createfingerprint stays free text, as before; the rule's content joins the skill digest (so the cache key) only when declared. Only strings are ids: a numeric id is never matched. - E, a refusal is a guard violation. The rule is part of the action guard
(
horae.engine.guard.check_intents,task_fingerprint), so a refusal is the existingguardviolation and aguard_violationstep error (the step isdegraded, nothing of the batch is routed), and a cached output is re-guarded on reuse and dropped when refused (decision 46). The detail is fixed text with the position and the field, never the fingerprint:skill:<skill> proposed task.create #<n> with a fingerprint not from the input infingerprint`. Skill evals run the same check (judge_intents). It does not reusecheck_task_fingerprints(thetask.update_statuscheck, routing rule 4, which lives inhorae.engine.executorand fails asintent_unrouted): the executor imports the guard, and the issue asks for a guard violation. Both read the viewed input as exact strings;horae.engine.viewpath` holds the path reading the new code shares. - F, not done: a link template. Item 3 (
link_templateunderlinks: none, built by the core from the fingerprint) is left out. Routing picks thetasksentry from the task's link, so an entry-owned template would have to choose the entry before the link exists; that circularity is not small. A skill underlinks: noneproposes tasks without a link for now. A follow-up could add the template to theactentry (link_template+link_fingerprint_prefix, id URL-encoded, result checked against the entry's ownlink_prefix). - G, what plugin-gmail changes. In
skills/gmail/triage-mail/skill.yaml, addtask_fingerprint: {ids: "[].data.needs_interpretation[].id", prefix: "gmail:"}; inexamples/triage-mail.pipeline.yaml, replaceon_unchanged_input: skipby (keeping it is harmless)skip_when_empty: ["[].data.needs_interpretation"], and say in the prompt that a task'sfingerprintisgmail:+ the mailid.
- A,
Provisional decisions (#162, pending maintainer review)¶
-
Accent folding, and plugin-declared personal fields the core enforces (#162). Provisional. Found by plugin-school-fr#4 (plugin-school-fr PR #7). Compatible additions: an optional
provides.personal_fieldsinplugin-manifest/v1.jsonand an optionalplugins.<name>.personal_fieldsinlockfile/v1.json(both regenerated;skill/v1.jsonis unchanged). Decision 62 is taken by open PR #155; 63 to 67 are merged. It amends decision 47 C (matching) and E (when de-identification runs).- A, accent folding. The matcher compares letters accent-folded on both sides,
the known value and the scanned text: case-folded, decomposed (NFD), nonspacing marks
(
Mn) dropped (horae.llm.deid.fold).Zoe,ZOE,zoéand an NFDZoéall match a knownZoé, and a knownZoematches all of them. A letter run now also holds the combining marks that follow a letter (the main combining blocks), so a mark NFKC could not compose (Zo̱e) does not cut a name in two; a token made of marks only folds to itself (a symbol is never empty). Whole letter runs only, as before:Léonever matches insideLéonard, unlessLéonardis itself a known value. The span of the text is replaced, whatever its spelling; re-identification puts back the canonical text (the classed leaf, personal value or vocabulary term first registered for those folded tokens), never the span as written:ZOEcomes back asZoé, asALICEalready came back asAlice(decision 47 G). Two classed values that fold alike (Zoé,Zoe) share a pseudonym.DEID_VERSIONis 3 (part of the cloud cache key: older entries are a miss once). - B, the declaration.
provides.personal_fields: {<tool ref>: [view paths]}, e.g.{school-fr.homework: ["children[].first_name", "homework[].teacher"]}. A key is one of the plugin'ssourcesortransforms; the paths use theViewPathsyntax of a skill'sinput_view, relative to that tool's output (not to the step input), 1 toMAX_PERSONAL_FIELDS(64) per tool, none under another and none disagreeing with another on a value's shape (pydantic-only rules). A mapping keyed by ref, notsources[]objects:provides.sourcesstays a list of refs that every reader (host, replay, marketplace, SDK) already uses. The lock records it with the approved plugin (LockedPlugin.personal_fields, paths sorted, left out when empty, so a lock without any is written exactly as before and an older core still reads it). The installer (#46, after PR #155'sInstalled.lock_entry) copies the manifest's declaration; no approval is needed, since a declaration only adds protection. In force is the union of the installed manifest's and the lock's (each tool's paths reduced to the outermost ones,merge_personal_fields): a manifest edited after approval, or a stale lock, can never drop a field.horae replayreads the lock's (LockRegistry), so a replay de-identifies as the run did. - C, which output reaches which step. One value flows through a run (the engine's "data between steps"); the plan follows the declared paths along it:
- after a
collectstep, each declared pathpof a source of that step is at[].data.pof the step's output ([].data[].xfor[].x). The class applies to every element of the list, so another source's field at the same path is protected too (over-protection, never under); - a later
collectstep starts a new value: its own sources' paths replace them; - a
transformthat declarespersonal_fieldsreplaces them with its own paths, relative to its output: it takes responsibility for where personal data went; atransformthat declares none, when personal paths are in force, loses them (the core cannot know where it put them); one that runs before any personal path changes nothing; - every tool that ran adds the values found at its declared paths (every string leaf and object key at or below them, NFC, non-empty) to the run's personal values, whichever step it ran in;
- at the
llmstep, the located paths are added to the skill's input view options as{class: person}, applied to the viewed input (the view keeps the input's shape): a skill classperson,email,phone,placeoramountat or above a path already hides it and is kept; afree_textclass at or above it (which means the same as no class) and any class below it are dropped, so no classed path lies under another. The personal values are knownpersonvalues (with their name parts, decision 47 C) looked for in every string and key of the viewed input. So a skill without classes is protected, and so is a name mentioned in a description the skill views while it does not view the field itself. - A personal path the skill's view does not select is not an error: that field is not sent at all, and its values are still looked for in what is sent.
- D, cloud only. As decision 47: a local alias is sent the viewed input unchanged. The
request is marked
classifiedwhenever personal paths or values reach the step, so without a policyModelBackendsrefuses it for a cloud alias (deid_required). - E, fail closed (nothing is sent, nothing is billed; the messages name a tool and a path, never a value), only for a cloud alias:
- while planning, an
llmstep after a transform that lost personal paths fails withdeid_unavailablebefore any plugin is called (an alias the policy cannot classify counts as cloud); - at the step, an output that contradicts the shape of its declared path (an object
where the path reads an array, a scalar where it reads either; an absent key or
nullis fine) degrades it withdeid_unavailable: the field cannot be located; - the pseudonymizer refuses (
deid_unavailable) more thanMAX_PERSONAL_VALUES(4096) values, a value longer than 1 KiB or 48 tokens (it could not be found in text), and, after rewriting, any personal value still found in clear in a string or key of what would be sent (pseudonyms put aside; a check against its own bugs). The cache, a replay's reuse and the repair retry all use the same de-identified input (decision 47 E: an entry is reused only with the same de-identified digest). - F,
horae eval. A case's input is read as acollectoutput: an element whosesourceis a tool withpersonal_fieldsgets the same paths and values, offline and live. Amended by M (#165): the source is resolved among every pluginhorae evalknows, not only the skill's own. - G, limits. Not matched: a value of fewer than 2 characters in text, a name part of
fewer than 3 letters (
AlofAl Martin; 2 in a script without spaces, J), nicknames, initials, typos and transliterations (ZoëisZoeby folding,Zojais not). A whole number of fewer thanMIN_NUMBER_DIGITSdigits, or a fraction, under a personal path is protected where the path is located, not in text (L). Folding over-matches (ZoeandZoéare one name). The declaration is as good as the plugin that writes it. - H, SDK 0.7.0.
Plugin.source(ref, personal_fields=[...]),Plugin.transform(ref, personal_fields=[...])(also thepersonal_fields=argument ofSource/Transform), andmanifest(..., personal_fields={ref: [paths]}), written asprovides.personal_fieldsonly when non-empty and checked like the core (a tool of the plugin, a path, 1 to 64, no duplicate, overlap or shape disagreement). - I, what plugin-school-fr changes. Require
horae-sdk>=0.7; register each source that returnsnormalize(...)data withpersonal_fields=list(DEIDENTIFIED_FIELDS)(children[].first_name,homework[].teacher,grades[].teacher) and regenerateplugin.yaml(python -m horae_school_fr --manifest), which then holdsprovides.personal_fields: {<source ref>: [...]}; keepinput_view()as guidance; dropNameScrubber(the core now folds accents) or keep it as harmless defence in depth, and fliptests/test_deid.py's accent test from documenting the gap to asserting thatZoeis caught, plus a test that a skill without classes sends no name; update the README's "Limits" (accent folding done, a skill without classes is now protected).
Amendment (#165, the review of #163).
DEID_VERSIONis 4 (the matching changed: older cloud cache entries are a miss once).plugin-manifest/v1.jsonandlockfile/v1.jsonare regenerated (apersonal_fieldspath may carry thefree_text:prefix); horae-sdk 0.9.0. - J, scripts without spaces, names glued to another script. A letter run is cut where its script changes (the first word of the letter's Unicode name:LATIN,CYRILLIC,GREEK...), and into single letters (each with its combining marks) in a script written without spaces between words: Han, kana, Bopomofo, Hangul (a particle is glued to a name:민수가), Thai, Lao, Khmer, Myanmar, Tibetan, Yi (horae.llm.deid._spans). Known values and scanned text are cut the same way, soZoéis found inZoé様,宿題はZoéがandZoéΣ,山田in山田さんは,山田花子in今日は山田花子さんが. Within one script that has spaces the whole-word rule stands:Léonever matches insideLéonard, norZoéinsideMarieZoé(a limit: cutting at a case change would also cutMcDonaldorDeVries, whose folded forms must keep matchingMcdonaldandDEVRIES, and match names inside ordinary words). A name part written in a script without spaces needs 2 letters, not 3 (花子of山田 花子; a Han or Hangul letter is a syllable); a single letter is never looked for. The middle dots·and・separate name parts (玛丽·杜邦,マリー・デュポン). In those scripts a value over-matches inside a longer word (山田in山田町), privacy over meaning, and a value of more than 48 letters is too long to be looked for (one token per letter). The check after rewriting (E) reads text with the same tokens, so the scanner and the backstop share every rule. - K, scan-only free-text fields. Apersonal_fieldspath may be prefixed byfree_text:(free_text:messages[].body): free text that may mention personal data. It is followed through the plan like any personal path (a transform that drops it fails closed for a cloud alias), its shape is checked, and at thellmstep it is classedfree_text(scanned for the personal values and the vocabulary; the request isclassified, so de-identification runs, or a cloud alias without a policy is refused), unless a classed path lies at, above or below it. Its content is not a personal value: it is neither replaced as a whole nor looked for elsewhere, so a long body never makes the step refuse. A plain personal field keeps the hard refusal of a value over 1 KiB or 48 tokens (E). A prefix, not a new key or an object: the declaration stays a list of strings, so the installer copies it into the lock as before; the approval prompt lists scan-only paths apart ("scanned ... not de-identified as values"), andhorae plugin upgrade(decision 73) shows turningxintofree_text:xas the personal fieldxremoved, a widening that needs approval, andx (scan-only free text, not de-identified as a value)added. In the union of the manifest's and the lock's (B), a path personal in one and scan-only in the other stays personal, and a scan-only path at or under a personal path is dropped. One tool's paths, prefix or not, may not overlap or disagree on a shape. - L, personal numbers. Every whole number (not a boolean) of at leastMIN_NUMBER_DIGITS(6) digits at or below a personal path is a personal value too (its decimal digits, without a sign; an integral float too): it is looked for in text (a whole digit run), whatever the separators in a run of digits and phone separators: by its last nine digits anywhere in the run when it has nine or more (33612345678is found as06 12 34 56 78), by all its digits at the end of the run after at most four other digits (a trunk0, a country code) when it has 6 to 8 (91234567in+65 9123 4567,123456in123-456and0123456); the same for a personal string written as a phone number. A number of the input (an integral float too) outside its own field is replaced ([PERSON_n], a string) when its digits equal a personal number's or match it by the same rule (612345678for33612345678). The check after rewriting applies the same rules to text and numbers. Six digits: phone numbers, national, student and account identifiers have six or more, while years, days, counts, quantities and most amounts have fewer and would otherwise be replaced all over the input. Shorter numbers and fractions are still pseudonymized where they sit (their path is classedperson). - M,horae evalacross plugins. A case element'ssourceis resolved as acollectstep resolves its tool (PluginRegistry.plugin_for_tool), through every pluginhorae evalknows: the instance'sHostRegistry(manifests andhorae.lock, the declarations in force a run uses, B), or, with--plugin-dir, every valid manifest of the folder (horae.evals.ManifestRegistry; two plugins providing one tool are refused, as the host does). A limit remains: a case is read as acollectoutput, so a case that stands for a transform's output (nosourceelements) gets no declared fields; eval cases are synthetic.Amendment (#189, a follow-up of the review of #187).
DEID_VERSIONis 5 (more text is matched: older cloud cache entries are a miss once). - N, given names of unspaced CJK and Hangul names. A full name stored without a space (王小明,김민수,山田花子) had no name parts, so its given name alone (小明的作业,민수야,花子さん) was sent in clear, and a one-letter surname is never a part (王老师for王 小明). Now each name part written only in Han letters (with or without kana) or only in Hangul syllables, of at most 6 letters (MAX_UNSPACED_NAME_LETTERS), is also split into a surname and a given name at every length its script allows (horae.llm.deid._surname_lengths), and each piece of at least 2 letters is a name part of its own, mapped to the whole name: - Korean: a surname of one letter (김+민수), of two for a compound surname of a short known list (KOREAN_COMPOUND_SURNAMES:남궁,황보,제갈,선우...), one or two for an unknown name of four letters or more; - Chinese and Japanese (Han alone cannot tell them apart): one or two letters up to four (王+小明,欧阳+娜娜,山田+花子,林+花子; a 3-letter name also gives王小, a 4-letter one田花子), one to three from five (長谷川+一郎). Every split is kept, so a wrong guess pseudonymizes more, never less; a Chinese compound surname needs no list (the two-letter split covers it); - kana alone is not split (mostly a foreign name,マリー), nor a longer part, nor a part in any other script. A one-letter surname (a one-letter part, or the first letter of a part split after it; of a two-letter part only when it is the whole name,王明) is looked for only when a title follows it, glued or after one white-space run (HONORIFICS:老师,先生,女士,小姐,校长,さん,サン,様,君,ちゃん,씨,님,선생님... simplified and traditional; halfwidth kana reads as fullwidth); only the surname is replaced ([PERSON_1]老师), and re-identified as the whole name (王小明老师, privacy over meaning, as for any part). A single letter is still never matched alone (王是,国王,김가). Every title entry is added after every person's name parts (in the scanner and the backstop), so a real part always wins (君of王君 Wangis never taken as the title of王of王小明). Overlaps. Matching is leftmost-longest without overlap, so a piece of one name could end inside another known value and leave its rest in clear (王小of王小红in王小明,明sent). A match that ends inside a run of letters of a script without spaces is therefore replaced together with every known value that starts inside it and ends past it, extended until none does, as one pseudonym (the first match's person):王小明is[PERSON_1],양양민for양민is[PERSON_1]; a title is kept only when no other known value starts inside the match (王 君华for王君华is[PERSON_1], not[PERSON_1] 君华). Elsewhere a match ends at a word's edge and the rest is unchanged. The scanner and the backstop (E) build their parts and titles with the same functions (_name_parts,_titles), for every personal value whatever its length (王with王老师). Names in scripts with spaces are split exactly as before;MarieZoé(glued within one script) stays a limit. The tradeoff. Two Han or Hangul letters are a common word as often as a name, so a given name over-matches:小明inside大小明显,花子in unrelated text,민수inside시민수업(a civics class), and the extra splits (王小,田花子) do the same. It pseudonymizes more text than the name, which can blur what the model reads (and, at worst, a sentence comes back with the whole name where only the word was), but it never sends a name in clear: the failure is toward refusing, the direction decision 47 chose; an overlap union replaces a whole run of letters that held two names under the first one's pseudonym. A title before the surname (老王,小王), or split from it by a sign (王・老师) or inside itself (王老 师), is not looked for:小+ surname would also hit common names and words (小林), and it leaks one letter at most. - A, accent folding. The matcher compares letters accent-folded on both sides,
the known value and the scanned text: case-folded, decomposed (NFD), nonspacing marks
(
Provisional decisions (#45, pending maintainer review)¶
- Per-plugin virtual environments (#45). No schema change.
horae plugin addpasseshorae.marketplace.environment.PluginEnvironmentasinstall(..., prepare=)(decision 62 G): it builds the plugin's own venv in the verified scratch tree,<tree>/.venv, before the atomic rename, soplugins/<name>/.venvexists exactly when the plugin does, and a failure leaves nothing. Plugins never share a dependency.- A, what a plugin ships. A
pyproject.tomlwith a[project]name and a committeduv.lock, else the install is refused before uv runs. In the lock, every package but the plugin's own project (whose source is the tree,.) comes from an index or URL, has at least one wheel, and has asha256hash for each of its files. An sdist-only package, agitsource (no hash), another in-tree package or one outside the tree is refused, the message naming it. A committed.venvis refused. - B, the build backend allow-list.
build-system.build-backendmust be one ofhatchling.build,setuptools.build_meta,uv_build,flit_core.buildapi,pdm.backend;build-system.requiresmay name only that backend's distribution (andwheelfor setuptools), never with a direct URL;backend-path(an in-tree backend) andtool.uv.package = false(a virtual project, which would not be installed) are refused. The allow-list covers the only build that happens (dependencies are never built, C). It narrows, but does not remove, code execution at install time: a backend runs the project's own build code (setup.py, a hatch build hook) as the Horae user, before #46 shows the permissions, and the backend's own version is not hash-pinned (uv resolves build requirements, which are not inuv.lock).uv_buildis recommended: uv carries it, nothing is fetched. Isolation is M5 (#51, #52); accepted for first-party plugins meanwhile (T04,docs/security.mdT39). Provisional amendment (#191, decision 79 G). A plugin that is not first-party is never built:uv sync --locked --no-dev --no-install-projectinstalls only its dependencies (same hashed-wheel rule),dynamicmetadata is refused (uv would run the backend for it), and a.pthmakes the tree's sources importable inside its container. So the residual risk above is first-party only. Such an install also uses its own uv cache, never<state_dir>/uv-cache, and every lock's registry files must come from the registry's own host (decision 79 H). - C, the commands.
uv venv --relocatable --no-project --python <python> .venv, thenuv sync --locked --no-dev --no-editable --python .venv/bin/python --no-build-package=<name>for every dependency of the lock, both with--no-config. Only the plugin's own project is ever built: a dependency installs from a hashed wheel, and when none fits the machine uv refuses rather than build its sdist (whose backend, not on any allow-list, would run code).--lockedreads the lock and fails if it no longer matchespyproject.toml(never re-resolves, never writes;--frozenis not used, it would skip that check); uv checks every file against its hash; the project is built and installed non-editable, so the tree's sources are not imported at run time. The venv is relocatable (its scripts find their interpreter relative to themselves), so it works after the rename; the install checkspyvenv.cfgstill says so. - D, the interpreter.
<python>is Horae's own interpreter (sys.executable; in the image/opt/venv/bin/python, i.e. the image's CPython), a constructor argument.requires-pythonis honoured: a plugin that does not accept it is refused. No Python is ever downloaded (UV_PYTHON_DOWNLOADS=never), so what the venv links to is on the machine at run time too. - E, uv's environment. Built from scratch:
PATH=/usr/local/bin:/usr/bin:/bin, an empty temporaryHOME/TMPDIR,LANG=C.UTF-8,UV_NO_CONFIG=1,UV_PYTHON_DOWNLOADS=never,UV_LINK_MODE=copy,UV_PROJECT_ENVIRONMENT=<tree>/.venv,UV_CACHE_DIR=<state_dir>/uv-cache. Only the proxy and CA variables (*_PROXY,SSL_CERT_FILE,SSL_CERT_DIR) are inherited: they say how to reach the network, never what to fetch. NoUV_*/PIP_*index setting is inherited; the index is uv's default or the plugin's ownpyproject.toml, and the hashes pin the bytes either way.index_url(--default-index) is a constructor argument only, never ahorae.yamlsetting: tests pass a localfile://index. - F, limits. Each uv call at most 600 s; what the install writes at most 1 GiB: the
venv, uv's temporary directory (sdist and build environments) and what it adds to the
shared cache (its size before the install is the baseline), measured while uv runs
(killed past it);
pyproject.tomlanduv.lockat most 4 MiB each. uv's failures areInstallRefused(exit 3) when the lock, a hash orrequires-pythonis at fault, elseInstallError(exit 1); uv missing isInstallError. - G, run time: how
runtime.commandmaps onto the venv. A plugin directory with.venv/pyvenv.cfgand.venv/bin/pythonhas a venv (horae.plugins.host.env. plugin_venv). For such a plugin, a barecommand[0](python,python3, or a console script the project declares) is looked up in<plugin>/.venv/binfirst, then on the basePATH, and kept as found (not symlink-resolved: the venv'spythonis a symlink its interpreter needs asargv[0]). So a plugin writescommand: [python, -m, <module>]orcommand: [<console-script>]. An absolute command and a relative path are unchanged (the contract before #45; a relative.venv/bin/pythonresolves outside the plugin and stays refused). The child'sPATHstarts with<plugin>/.venv/binandVIRTUAL_ENVnames the venv. Every plugin child, with a venv or not, getsUV_OFFLINE=1,UV_PYTHON_DOWNLOADS=neverandPIP_NO_INDEX=1(OFFLINE_ENV; they were already denied as secret names). Running a plugin needs neither uv nor the network. - H, upgrade. The venv belongs to the installed tree. An upgrade (#47) installs the new
version through the same
install(..., prepare=PluginEnvironment(...))into its own scratch directory, so it gets a fresh venv from its own lock, and swaps the tree; a venv is never updated in place. #48 (install from a git URL) passes the sameprepare. - I, the container image. The image ships no uv (decision for #40: no package manager
at run time) and needs none to run plugins.
horae plugin addinside the container fails with "uv is not installed" (exit 1). A venv links to the interpreter that built it, so it must be built by the image's own Python: giving the image an install-time uv (or an installer variant) is a follow-up. The built-in plugins run from/opt/venv, unaffected.
- A, what a plugin ships. A
Provisional decisions (#46, pending maintainer review)¶
- Permission approval at install, and
horae.lockwritten byhorae plugin add(#46). No schema change (lockfile/v1.jsonis as decision 68 left it). Decision 69 is left to #45. It completes decision 62 F: an install is now approved and pinned in one command.- A, the prompt. After the verified install (decision 62 A to D), before the tree is
moved into place (the
preparehook),horae plugin addshows whatplugin.yamlasks for, grouped and labelled: network (https hosts); local network (plain http allowed) on its own (decision 66); secrets, required and optional; intents, each with a one-line meaning (horae.marketplace.approval.INTENT_MEANINGS, one for every intent of the closed set, tested); paths, read and read-and-write.provides.personal_fieldsare shown as information ("de-identified before cloud models"), never approved (decision 68 B). With--jsonthe prompt goes to stderr and stdout keeps one JSON document. - B, approval. Interactive confirmation, default no (an empty answer, end of input
or Ctrl-C is a no).
--yes/-yapproves only whenhorae.lockalready has an entry for this name with the same version and commit and permissions identical to what is asked (canonical comparison, extra grants included), e.g. a Docker build from a committed lock; otherwise it is refused, naming the difference. No terminal (stdin is not a TTY) and no--yesis refused. Every refusal is exit 3 (approval_refused) and leaves nothing inplugins/andhorae.lockunchanged. An interactive approval of a plugin whose lock entry differs (another version, from a lock with no installed tree) replaces that entry, and says so first. - C, extra grants.
--allow-host HOST(aHostname) and--allow-local HOST:PORT(aLocalEndpoint), repeatable, add grants beyond the manifest; they are shown "(added by you)" and written to the lock. A lock may grant more than a manifest declares (the host refuses only less, decision 66): this is how a user approves their own school or Home Assistant host. An invalid value is a usage error (exit 2). With--yesthey must be given again (the request must be identical to the lock). Nothing else can be added (paths, secrets, intents come from the manifest only). - D, the lock file.
horae.marketplace.lock: the whole lock is rewritten atomically (temporary file in the instance directory,fsync,rename,fsyncof the directory, the file's mode kept) under an exclusive, non-blockingflockon<state_dir>/horae.lock.guardheld for the whole add (read, install, prompt, write); a second writer is refused with exit 5 (lock_busy). Canonical text: the contract's serialization (plugins and lists sorted, emptynetwork_local/personal_fieldsomitted), then block-style YAML with sorted keys, no wrapping, a trailing newline, after the leading comment lines of the existing file (a new file gets a short default header). Re-serializing is byte-stable, and adding a plugin adds only its own lines (tested).horae initwrites its lock with the same function. Ahorae.lockthat does not validate is never rewritten. The entry isInstalled.lock_entry(approved); it must equal the approved one or the install is undone. If the lock cannot be written, the placed tree is removed (exit 1,lock_write_failed). - E, tier (docs/security.md T04). Before M5,
horae plugin addrefuses a plugin whose marketplace tier is notfirst-party, before anything is fetched (exit 3,tier_refused, pointing to M5). The tier is a claim in the index file, sofirst-partyis believed only from the default Horae marketplace (FIRST_PARTY_INDEXES): an index the user added cannot vouch for itself.require_installable(name, tier, index)is the one check; a direct install from a git URL (#48) passestier=None, which is refused the same way. Provisional amendment (#191, decision 79). "Before M5" is now "under the process runtime": a plugin that is not first-party (another tier,first-partyclaimed by an index the user added, a direct install) installs when its effective runtime inhorae.yamliscontainer, and only then; first-party plugins install under either runtime.require_installable(name, tier, index, runtime=...)stays the one check, and the lock recordstierandindexfor such a plugin so the host can enforce it at run time. - F, at run.
HostRegistry.from_directoryalready refuses a manifest asking for more than the lock grants and a version other than the locked one. It now also reads the install recordplugins/<name>/.horae-install.json(decision 62 F) when there is one: its name, version, repo and commit must be the lock entry's, else the plugin is refused (plugins_invalid): an installed tree that is not the approved one. The record must be a regular file (no symlink) of at most 64 KiB holding a JSON object. A plugin without a record (the built-in oneshorae initinstalls, a plugin copied by hand) is checked by its manifest only: an accepted gap until the files of a plugin are pinned (#47 or M5).
- A, the prompt. After the verified install (decision 62 A to D), before the tree is
moved into place (the
Provisional decisions (#48, pending maintainer review)¶
- Direct install from a git URL (#48). No schema change.
horae plugin add https://<host>/<owner>/<repo>@<sha>installs without any marketplace.- A, the reference (
horae.marketplace.direct). An argument holding:or/(a plugin name never does) is a git URL. It must start withhttps://(nohttp,file,ssh,git,ext::or scp-stylegit@host:path), carry no user info, be aGitRepoUrl(the contracthorae.lockstores: DNS host, no port, IP literal orlocalhost, no./..segment, query or fragment) and be pinned after its last@to a full commit SHA (CommitSha: 40 lowercase hex digits, or 64 for a SHA-256 repository). A tag, branch or abbreviated SHA is refused: what is approved is one commit. Any refusal is a usage error (exit 2,usage); no error repeats the URL (a token may sit in its user info, query or fragment).--preand--offlinedo not apply to a URL (no index is read, the repository must be fetched): each is a usage error (exit 2). - B, the gate (docs/security.md T04). A direct install has no marketplace tier, so
require_installable(url, None, None)refuses it before M5, after the reference and the instance are read and before anything is fetched (exit 3,tier_refused). The whole path behind the gate is implemented and tested with it open; lifting it in M5 isapproval.DIRECT_INSTALLS = True. Provisional amendment (#191, decision 79).DIRECT_INSTALLSis gone: the runtime is the one switch. A direct install is refused before anything is fetched whenhorae.yamlruns no plugin in a container, and once the commit'splugin.yamlnames the plugin (before approval) unless that name's effective runtime iscontainer. - C, the fetch (
PluginInstaller.install_commit). The commit is never fetched by its id: a forge may serve, through a repository's URL, objects that exist only in a fork or a pull request (GitHub does), and the approval and the lock would then name the trusted repository for a fork's code. Insteadgit ls-remote --refs -- <url> refs/heads/* refs/tags/*lists the repository's own tips (names ofA-Z a-z 0-9 . _ / -only;refs/pull/*and anything else is ignored; none is a refusal, more thanMAX_DIRECT_REFS= 1000 too), an empty bare repository fetches exactly those refs (--depth=MAX_REACH_DEPTH, 1000 commits,--no-tags --no-recurse-submodules, the byte budget of the download), andmerge-base --is-ancestor <sha> <tip>^{commit}must hold for at least one tip. Otherwise, a commit further than the depth from every tip included, the install is refused (exit 3,install_refused): fail closed. No tag is compared: the SHA is the pin. Then the same steps and limits as decision 62: the tree checks (paths, file count and size, no submodule, no escaping symlink), the hardened git (https only, no hook, no LFS smudge, no filter, no user or system config), the checkout without.git, and the atomic placement. The name and version are those of the commit'splugin.yaml; the name is checked againstplugins/once the manifest is read, before approval. - D, approval and lock. The same
preparechain as a marketplace install (decision 70): the permissions are shown and approved first, then the venv is built (decision 69), so a declined plugin's dependencies are never installed. Thehorae.lockentry is the usual one:versionfrom the manifest,repothe URL as given,committhe SHA.--yespasses only when the lock's entry for that name has the same repository (exact string), version, commit and permissions. The--jsonreport hastierandindexnull. - E, open. A lock entry does not say whether it came from a marketplace or a direct
install (
LockedPlugin.commitis documented as the commit the version's tag points to, which a direct install does not check).upgrade(#47) will need to tell them apart: asourcefield, or "no index lists this repo", is left to it. (Settled by decision 73 A:source: direct; #191 adds the upgrade of a direct install, decision 79 E.)
- A, the reference (
Provisional decisions (#133, pending maintainer review)¶
- A pipeline pack's pipelines are installed by
horae plugin addintopipelines/<plugin>/, approved with the plugin and pinned inhorae.lock(#133). One additive schema change:lockfile/v1.jsongainsplugins.<name>.pipelines(G). (#48 took 71.)- A, where.
<instance>/pipelines/<plugin>/<pipeline>.yaml, one directory per pack. The instance loader (horae.config.loader) readspipelines/*.yamlas before and now alsopipelines/<dir>/*.yaml, one level down; a directory whose name starts with.or has a suffix, and a symlinked directory, are skipped. A pipeline'snameis still its file's stem and still unique in the whole instance (a second definition is the existing "defined twice" problem). A directory per pack, not a prefix in the file name, because the name of a pipeline is the file's stem and a prefix would change whathorae runis called by; and so that remove and upgrade (#47) delete exactly one directory. - B, what is a pack. A plugin whose manifest lists
provides.pipelines. The pack'spipelines/holds exactly those names as plain<name>.yamlfiles (a missing file, an undeclared one, a.yml, a directory or a symlink is a refusal). A plugin that lists none is not a pack and installs nothing here. - C, when and how. Inside the existing flow, as a
preparestep before the tree is moved into place. The check runs first (it only reads, so the approval can show what it found); the approval and the venv build follow: every file is read once (at most 1 MiB, regular file, no symlink, resolving inside the tree), parsed with the loader's safe YAML reader and validated as aPipeline, and itsnamemust be its file's. The installer itself refuses a symlink underpipelines/in the git tree (a checkout withcore.symlinks=falsewould turn it into a file holding the link target). Any failure isinstall_refused(exit 3) and nothing is written. The validated bytes are written to a scratch directorypipelines/.install-*and renamed topipelines/<plugin>/after the tree is placed; if that or thehorae.lockwrite fails, both are undone. - D, never overwrite. The install is refused if
pipelines/<plugin>/exists (the plugin is not installed at that point, so it is not ours) or if another pipeline of the instance already has the name of one of the pack's. #47 must delete the recorded files before a reinstall, which is what makes "a file this pack installed before" replaceable. - E, the record. The relative paths are added to the install record, key
pipelines(plugins/<plugin>/.horae-install.json, decision 62 F), for #47. The host compares only name, version, repo and commit, so the extra key is ignored there.--jsoncarriespipelinestoo. - F, what is not checked. Instance-level references (a model alias, a tool nobody
provides, a time zone) are checked by
horae doctorand at run time, as for a pipeline written by hand: a pack cannot know the instance. - G, approval and the lock (security review). A pipeline is code the core runs on a
schedule, so it is approved like a permission. The prompt lists, per pipeline, its name,
its trigger (cron and time zone, or "manual or external trigger only") and the tools and
skills it calls.
horae.lockrecordspipelines: {<name>: <sha256 of the file>}for the pack (left out when empty, names sorted);lock_mismatchcompares it, so--yesrefuses a pack whose pipelines differ, and the entry written must equal the approved one. - H, only an enabled, locked pack runs. The loader reads
pipelines/<plugin>/*.yamlonly if<plugin>is listed underplugins:inhorae.yamland has an entry inhorae.lock, and a file only if its SHA-256 is the locked one for that name (else a problem naming the file; an unlisted name counts as not approved). So the scheduler,horae runand the budgets see no pipeline of a disabled or removed plugin. Installing does not enable: the output says so. - I, tools of other plugins: warn, not refuse. A pack's own manifest has no dependency
list, and real packs exist to call other plugins (
obsidian.*,ntfy.*), so refusing would make every pack unusable. The prompt instead prints, under each such pipeline, awarning: calls plugins other than <pack> (<namespaces>)line; those tools run with the permissions of the plugins that provide them, whichhorae.lockalready pins. A pack dependency list is a possible follow-up. - J, review fixes. A pack is recognised by structure, never by name: the loader treats a
file as a pack's when its directory is not
<instance>/pipelinesitself, so a plugin namedpipelines(installed topipelines/pipelines/) gets every gate; the namepipelinesis also refused at install. Apipelines/<dir>is a pack's only if the lock entry of that plugin has a non-emptypipelinesmap; otherwise the directory is ignored (as before this decision, so an instance upgraded from an older lock keeps working) with a logged warning. The prompt also prints each call's parameters (act and notify targets:path,mode,url,link_prefix,topic...; at most 160 characters each) and eachllmstep's model and budget. - K, amendment (#173): exclusive placement. D's "never overwrite" was a
lexistscheck followed byrename, which on POSIX silently replaces an empty directory created in between. The scratch directory is now placed withrename_noreplace:renameat2(RENAME_NOREPLACE)on Linux, an exclusivemkdirof the target plus a move of the files through directory descriptors elsewhere. A target that exists, empty or not, is refused (install_refused, nothing left behind, the lock not written). The same primitive moves an upgraded pack's old directory aside and puts it back on rollback (decision 73);removeonly deletes. No schema change.
- A, where.
Provisional decisions (#47, pending maintainer review)¶
horae plugin upgradewith a permission diff,removeandaudit(#47). One additive schema change:lockfile/v1.jsongainsplugins.<name>.source(A). Commands inhorae.cli_plugin_manage; the diff and the swap inhorae.marketplace.upgrade, what is read from disk inhorae.marketplace.audit.- A, where a plugin came from (settles decision 71 E).
LockedPlugin.sourceisdirectfor a direct install from a git URL and absent for a marketplace install, so every lock written before stays byte-identical and valid (a built-in plugin ofhorae inithas none either). It is approved with the rest:lock_mismatchcompares it, so--yesnever turns one kind into the other. The install record (decision 62 F) also getssourceand, for a marketplace install, thetierandindexthat resolved it: information forauditonly (the host still compares name, version, repo and commit). A lock entry, not "no index lists this repo", because the answer must not change when an index does, and because the lock is what the user reviews and commits. - B,
horae plugin upgrade NAME[@VERSION](--pre,--offline,--yes,--allow-host,--allow-local,--allow-downgrade,--json). Only a plugin installed byhorae plugin add(a lock entry and a tree, a real directory with an install record naming it) can be upgraded; a built-in or hand-copied plugin isnot_installed(exit 3). Asource: directentry goes throughrequire_installable(name, None, None): refused before M5 (tier_refused), and behind the gate still refused, pointing toremovethenadd URL@SHA(an upgrade resolves through a marketplace). Superseded by decision 79 E (#191):upgrade URL@SHAupgrades a direct install. The new version is resolved asadddoes (marketplace_pins,--pre) and the tier rule applies again (a plugin whose index no longer saysfirst-partyis refused). A lower version than the installed one is refused (downgrade_refused, exit 3) unless--allow-downgrade; a version the index now pins to another commit than the installed one is refused (install_refused, a moved release or a tampered index); the installed version and commit with nothing new asked is a no-op (exit 0,upgraded: false). - C, the permission diff. Against the
horae.lockentry (what was approved), item by item,+added,-removed,~changed: repository, source, network, network_local, secrets (required and optional together; a move between them is~), intents, paths read and write, personal fields and pack pipelines (by digest). Widening, marked "new: needs approval": anything added; a pipeline added or changed (new code the core runs); a personal field dropped (less protection, decision 68); another repository or source. Removals are shown but need nothing. When something widens, the full request (decision 70 A, with the pipelines' calls) follows the diff. - D, grants. The hosts and local endpoints the user added (
--allow-host,--allow-local) are kept and said so, and do not widen. New flags add to them and do widen. Nothing else is carried over: a host the old manifest declared and the new one drops is gone. Amendment (#175). The first version worked the user's grants out as the lock's hosts minus the hosts of the installedplugins/<name>/plugin.yaml. That file is not verified (a plugin running as the user can rewrite it, and a killed upgrade can leave the new tree in place under the old lock), so a host the old version declared could be relabelled "added by you" and stay granted.addandupgradenow record the user's grants in the lock entry,plugins.<name>.user_grants(network,network_local), and an upgrade carries over only those. A lock entry, not the install record: the lock is what the user reviews, commits and approves, it is written atomically with the approval, anduser_grantsmust be a subset ofpermissions(a lock that lists a grant it does not give is invalid); the record lives in the plugin's own tree, the very place the bug came from, and a killed upgrade leaves the new version's record there. The field is optional and omitted when empty, so a lock written before it, or for an install with no--allow-*, is byte-identical;lockfile/v1.jsongains the optional property (additive).lock_mismatchdoes not compare it (the permissions it grants are what--yesapproves). Legacy entries have no record: the manifest at the pinned commit would need a fetch of the old commit (no clone is kept, and--offlinemust work), so nothing is carried over, failing toward fewer grants. The upgrade prints a note naming the old hosts and endpoints the new version drops and asks to pass--allow-host/--allow-localagain if the user added them; the next upgrade records them. - E, approval. Interactive confirmation, default no.
--yespasses only when nothing widens, which includes a lock that already approves the target (a lock committed from another machine: the diff is then empty). Without a terminal and without--yes, refused. Every refusal isapproval_refused(exit 3) with nothing changed. - F, atomic. Under the lock guard (decision 70 D), held from reading the lock to writing
it: the new version goes through the same hardened install (decision 62,
install(..., replace=True)), its pack pipelines are checked, the approval runs, and its venv is built (decision 69) in the scratch tree, which is then renamed toplugins/.upgrade-new-<name>-*(swept after an hour if a kill leaves it). Then, in order: the old tree toplugins/.upgrade-old-<name>-*, the new one toplugins/<name>, the old pack directory aside and the new one in, the lock written. Any failure undoes the steps done, newest first: the old tree, venv, pipelines and lock are as before (exit 1,upgrade_failed, or the install's own error). The old copies are deleted only once the lock is written. A kill between the two tree renames leaves noplugins/<name>(the host refuses to run,plugins_invalid) and the old tree in.upgrade-old-*, never swept:auditreports it. The venv is relocatable (decision 69 C), so the rename keeps it working.write_lock's commit point is its rename: thefsyncof the directory after it is best effort, and its failure is a warning, never a rollback. An error (or Ctrl-C) that arrives once the lock write has started is checked against the file: if the new lock is in place, the upgrade (or aremove, or anadd) is treated as committed and finished, so a lock and a tree never disagree while the message says nothing changed. - G, a pack's pipelines at upgrade.
pipelines/<plugin>/may exist only as a real directory holding nothing but the old version's own files: regular<name>.yamlfiles the lock approves for the plugin, each still with its locked digest. A file edited after approval, or any other entry, refuses the upgrade (it is never deleted: move it away or restore it). The name clash check of decision 72 D skips the pack's own directory. A plugin that was not a pack never touchespipelines/<plugin>/. - H,
horae plugin remove NAME(--delete-secrets,--json). Refused while the plugin is listed underplugins:inhorae.yaml(plugin_enabled, exit 3): the loader then reports a missing plugin and the instance stops loading, and its scheduled pipelines would stop mid-flight; disabling is an explicit step first. Refuse, not warn, so thatremovenever breaks a running instance. It removes the tree (with its venv,plugins/<name>/.venv), the lock entry and the pack's pipelines. The tree must be a real directory (a symlink is refused, never followed) with an install record naming the plugin; it is renamed aside (plugins/.remove-*) first, then the lock is written (on failure the tree is renamed back,lock_write_failed, exit 1), then deleted. A lock entry whose tree is gone is removed too (its pipelines checked against the lock). - I, what
removedeletes inpipelines/. Only files that are a pipeline the lock approved for this plugin and that the install record lists as exactlypipelines/<plugin>/<name>.yaml(a record naming any other path is ignored), each opened withO_NOFOLLOWthrough a descriptor ofpipelines/<plugin>/itself opened withO_NOFOLLOW(a symlinked directory or file is never followed), a regular file whose SHA-256 is still the locked one. An edited, foreign or extra file is kept and listed; the directory is removed only if it is then empty. - J, what
removekeeps. Its secrets (each listed with the reason), the files it wrote under itspaths, and the run history in the store: listed underkept. No flag deletes the files under its paths (they are the user's vault) or the run history (shared by every pipeline).--delete-secretsdeletes<secrets.dir>/<file>of each of its secrets that nothing else uses: no other locked plugin, no manifest underplugins/(locked or not, built-in included), nosecrets.refsname (a secret with an explicit reference is kept: delete it there by hand), model alias, push monitor or core secret, and no other{file:}reference or the de-identification vocabulary naming the same file, compared case-insensitively and by device and inode (a symlink or a second hard link to it keeps it). Only a regular file with one link is deleted (lstatthrough a descriptor of the directory,O_NOFOLLOW). Fail closed: a manifest underplugins/that cannot be read keeps every secret. A secret read from an environment variable, a symlink, or a file that cannot be deleted is kept too; each is listed with the reason. Values are never read or printed. - K,
horae plugin audit(--json). One row per plugin ofhorae.lockor ofplugins/(hidden entries apart): version locked and installed, source (marketplace,direct, orlocalwithout a record), tier and index from the record (nullwhen not recorded), enabled, the granted permissions, personal fields and pipelines, and the last activity: when the latest stored run whose record lists the plugin started (Store.plugin_activity, the store opened read-only;nullwithout a store). It readshorae.yamlandhorae.lockalone, not the whole instance, so it runs on an instance the loader refuses because of the drift it reports. - L, drift (exit 4,
EXIT_DIFFERENT; the JSON document is printed as usual withdrift: true):not_installed(locked, no tree),not_locked(a tree, no lock entry),tree_invalid(not a real directory),record_invalid,record_mismatch(record vs lock),host_refuses(HostRegistry.from_directoryrefuses it: a manifest asking for more, another version),venv_missing(a recorded install without.venv),pipeline_missing,pipeline_changed,pipeline_unapproved(against the locked digests), andleftover(plugins/.upgrade-old-*,.upgrade-new-*,.remove-*,pipelines/.upgrade-old-*). A plugin without a record is checked by its manifest only (decision 70 F). - M, exits.
upgradeandremove: 0 done, 1 configuration problem, a repository or index that cannot be fetched, an invalid or unwritable lock, 2 usage (a URL given toupgrade, a bad name or grant), 3 refused as above, 5lock_busy.audit: 0 no drift, 1 configuration problem or invalid lock, 4 drift.
- A, where a plugin came from (settles decision 71 E).
Provisional decisions (#49, pending maintainer review)¶
- A per-plugin container runtime (#49). One additive schema change to
instance/v1.json:plugin_defaults.runtime,plugins.<name>.runtimeand acontainersection (A, G). Code inhorae.plugins.host.container; operator guide in docs/operations/plugin-containers.md.- A, where it is chosen.
runtime: process | container, inhorae.yaml:plugin_defaults.runtime(defaultprocess, the behaviour before #49) andplugins.<name>.runtime, which wins. The operator chooses, never the plugin: the manifest and the lock do not carry it, so a plugin cannot opt out. A plugin ofhorae.lockwithout aplugins.<name>entry gets the default. - B, the engine: Docker, through its CLI.
docker run --interactivespeaks MCP over the container's stdin and stdout, as the process runtime does over a child's pipes; the host's transport, timeouts, restarts and redaction are unchanged. Podman is not supported yet: its networking (netavark) and rootless user mapping differ, and the guarantees below were verified on Docker only. The CLI iscontainer.docker(an absolute path) ordockeron the basePATH(/usr/local/bin:/usr/bin:/bin); it runs with an allow-listed environment (theDOCKER_*connection variables,HOME,XDG_*), never a plugin secret. The engine must be local:DOCKER_HOST, when set, and the endpoint of the context the CLI uses (docker context inspect) must be aunix://socket;tcp://,ssh://or anything else is refused (a remote engine would receive the secrets over the network and bind its own host's paths). - C, the container.
docker run --interactive --rm --init --pull never --log-driver none --user <uid>:<gid> --read-only --cap-drop ALL --security-opt no-new-privileges --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m,mode=1777 --network horae-plugin-<name> --mount type=bind,source=<plugin dir>,target=/plugin,readonly --workdir /tmp --entrypoint /usr/local/bin/python3 <image> -I -S -c <launcher> <command>. Docker's default seccomp profile applies (no--security-opt seccomp=is ever passed, nor--privileged,--cap-add,--deviceor a host namespace). The user is Horae's own uid and gid (so the plugin can read its tree, owned by Horae), and Horae refuses to start a container as root (uid 0). Only the plugin's directory is mounted, read-only; it holds the plugin's venv (.venv, decision 69), so nothing else of the host is visible: nothorae.yaml, the store,/run/secrets, other plugins or Horae's environment.--initmakes Docker's init PID 1, so a plugin's children are reaped and signalled with it.--log-driver none: the daemon keeps no copy of what a plugin writes (stderr may echo a secret).--pull never: nothing is fetched at run time. - D, the network. Each plugin gets its own bridge network,
horae-plugin-<name>, created on first use with--internal(no route out),com.docker.network.bridge.enable_icc=false(no container talks to another) andcom.docker.network.bridge.inhibit_ipv4=true(the host gets no address on it). The last one matters: on a plain internal network the host's own bridge address is the gateway, and every host service listening on0.0.0.0(Horae's API on a bare-metal install, sshd, a database) is reachable from the plugin; it was measured on Docker 29. Before every run's first start of a plugin, the network is inspected and must have exactly these properties, carry the labeldev.horae.network=plugin, be neitherConfigOnlynor take its configuration from another network (ConfigFrom), and every container already attached must be labelleddev.horae.plugin=<name>(a concurrent run of the same plugin) ordev.horae.egress-proxy(reserved for #50's proxy); a network of that name that does not (created by hand, by an older Horae) is refused, never repaired or deleted. Containers that join after that check are not re-checked during the run. #50 attaches its egress proxy to these networks; until then a container has no egress at all, andpermissions.networkandnetwork_localgrant nothing in this runtime (they still travel in_meta). - E, secrets. Never on a command line and never in the container's configuration (
docker inspectshows the image'sENVonly). The host sends the plugin's environment (the same one the process runtime builds, decision 28, with container paths:HOME=/tmp/home,TMPDIR=/tmp/tmp,VIRTUAL_ENV=/plugin/.venv, its declared secrets) as the first line of the container's stdin, one JSON object; a launcher run by the image's interpreter (python3 -I -S -c, its source is a constant ofhorae.plugins.host.container, visible indocker inspectand secret-free) reads exactly that line, byte by byte so nothing of the MCP stream is consumed, setsumask 077, creates the directories, and runs the plugin command as its child with exactly that environment (#188: it stays, so that it can read the cgroup's OOM count once the plugin is gone; it passes the stop signals on). The values cross the CLI's connection to the daemon (the local socket) and live in the plugin process inside the container, readable by root on the host as any process's environment is. The host zeroes the preamble's bytearray once written, best effort only: the values were also strings (Secret.reveal(), the environment mapping, thejson.dumpsoutput) and the event loop may copy the bytes, so copies remain in Horae's heap until collected. The write is bounded by the plugin's startup timeout (startup_timeoutpast it), so an engine that stalls cannot hang a run. - F, the command. Resolved against the plugin's venv only: a bare
command[0]must exist in<plugin>/.venv/bin(python, a console script) and runs as/plugin/.venv/bin/<name>; a relative path must stay inside the plugin directory (as in the process runtime) and runs as/plugin/<path>. An absolute command names a host path and is refused, and so is a plugin without its own venv (the built-in plugins, which run from Horae's own interpreter: setplugins.<name>.runtime: processfor them). - G, the image.
container.image, defaultpython:3.12-slim-bookworm@sha256:<digest>: the same pinned base image the Horae image is built from (thePYTHON_IMAGEof theDockerfile; a test keeps both equal and Renovate bumps them together). It must be pinned by digest (@sha256:and 64 hex characters), elsehorae.yamlis invalid. No image is built: a plugin's venv is linked to the interpreter that built it (decision 69 D), and the Horae image builds venvs with/usr/local/bin/python3.12, which this image has at the same path. So before a start the venv'spyvenv.cfgmust namehome = /usr/local/binand a 3.12 version, else the plugin is refused with a message saying so (a venv built by another interpreter, e.g. on a developer's machine, cannot run in it). The image must be present (docker pull <image>once; checked withdocker image inspecton each run's first container start). - H, fail closed. With
runtime: container, a missing CLI, an unreachable daemon, a missing image, a network that is not as in D, a venv as in G, a refused command, Horae running as root, or a path Docker's--mountcannot carry (a,or") fails the plugin with the new host error kindruntime_unavailable(nothing started; the plugin is unavailable for the rest of the run, like any failed start). The process runtime is never used instead. - I, stop. As in the process runtime (stdin closed, then
SIGTERM, thenSIGKILLof the CLI's process group; the CLI forwards the signals to the container), then alwaysdocker rm --force <name>(bounded, 10 s): a container whose plugin ignores EOF and signals is removed with everything it started. Containers are namedhorae-<plugin>-<random>and labelleddev.horae.plugin=<name>. A Horae killed withSIGKILLleaves its CLI's container running until the plugin exits on EOF;docker ps --filter label=dev.horae.pluginlists such leftovers (no automatic sweep: it could remove the container of a concurrent run). - J, Horae inside Docker. The image ships no Docker CLI and mounts no socket: the
container runtime is not available to the Horae image as published. The options and
their risks are documented in the operator guide (a socket mount is host root, T26; a
socket proxy narrows the API but not what
docker runcan do; rootless Docker or Podman on the host; a sidecar). Enabling one is a follow-up, and so is lifting the M5 tier gate (approval.DIRECT_INSTALLSand thefirst-partyrule, decision 70 E), which needs #50, #51 and #52 too. (Lifted forruntime: containeronly by decision 79, #191.) - K, left to the sibling stories. CPU, memory and PID limits and declared mounts are
#51; the egress proxy is #50; the malicious-plugin suite is #52. The argument builder
(
run_argv) is the one place they add flags. - L, cost. Measured (operator guide, "Latency and sizing"): a container start adds about
0.25 s and a stop about 0.2 s per plugin; a call costs the same as in the process runtime;
an idle container holds about 9 MiB. Threat rows T26, T27 and T42 to T45 of
docs/security.md.
- A, where it is chosen.
Provisional decisions (#56, pending maintainer review)¶
- MCP server authentication (#56).
horae mcp servegains a network transport, streamable HTTP (--http), and every request on it needs a bearer token. New modulehorae.mcp_auth, commandshorae mcp token create|list|revoke(horae.cli_mcp_token), store migration 9 (mcp_tokens). The tools and their contracts (decision 65) are unchanged.- A, tokens.
hmcp_and 32 bytes fromsecrets.token_bytesas unpadded base64url (256 bits, 48 characters). The prefix makes a leaked token recognisable by secret scanners and by Horae's log scrubber (F). A token is printed once bycreate(stdout;--jsonputs it intoken) and never again: the store keepsSHA-256("horae-mcp-token/v1\0" || token)only. Why SHA-256 and not a password hash: a slow KDF (argon2, scrypt, bcrypt) protects low-entropy secrets from guessing once the digest leaks; a 256-bit random token cannot be guessed whatever the hash speed, so a slow hash would only add a per-request CPU cost that any client could use to load the server. The label keeps this digest distinct from any other SHA-256 of the same bytes. No pepper: it would need a second secret and adds nothing against a 2^256 search. - B, stdio needs no token. A stdio server is a child process of the user's own MCP
client, reading the instance with the user's rights: whoever can start it can already
read the store and run
horae run. The operating system has authenticated the caller, and a token in the client's config would sit next to the instance path and add nothing. A stdio session is granted every scope (STDIO_SCOPES), the same as its user at the CLI; for #55, the approval of apipeline.runstays required over stdio too (the approval, not the transport, protects against a client steered by note text). The transport decides this, not the absence of an HTTP request: a tool served over HTTP without an authenticated user gets no scope (fail closed), andbuild_servertakesstdioas a required keyword (no default that would grant every scope). - C, scopes.
read(the three read-only tools; each tool checks it, else the tool errorinsufficient_scope) andpipeline.run(reserved for #55: lets a client ask for a pipeline's dry run and an approval; it never approves anything, the approval stays the user's, out of band).creategrantsreadunless--scopesays otherwise (repeatable). No wildcard, no admin scope, no token management over MCP. - D, store. Table
mcp_tokensin the instance store (<state_dir>/horae.db, 0600, state directory 0700, as every store):id,name(1 to 64 of[A-Za-z0-9._-], first a letter or digit; unique among the tokens not revoked),token_sha256(32 bytes, unique),scopes(space-separated),created_at, optionalexpires_at(--expires-in DAYS, 1 to 3650),last_used_at(written at most once a minute per token, best effort with a 100 ms busy timeout) andrevoked_at. Revoked rows are kept (list shows them); a revoked name can be reused. The store, not a JSON file, so a revocation and a last-use update never overwrite each other. - E, verification. Every request opens the store read-only (a WAL reader, so a
revocation committed a moment ago is seen: revocation applies to the next request; no
cache), reads every row, digests the presented token (a fixed dummy when it is not
token-shaped) and compares the digest with every row's using
hmac.compare_digest, without stopping at a match; revocation and expiry are checked only after. A missing, malformed, unknown, wrong, revoked or expired token costs the same work and gets the same answer:401, body{"error":"invalid_token","error_description":"a valid bearer token is required"},WWW-Authenticate: Bearer realm="horae", error="invalid_token",Cache-Control: no-store. OnlyAuthorization: Bearer <token>is read (scheme case insensitive, exactly one header); never a query parameter or a cookie. Every path and method is behind the check (no unauthenticated route, no OAuth metadata). A store that cannot be read is503(fail closed). An authenticated request carries the SDK'sAuthenticatedUser(itsclient_idis the token's row id, never the token), which is what the tools check scopes against. - F, never logged. No Horae code logs the header or the token; uvicorn's access log is
off and its log configuration not applied (Horae's redacting record factory stays).
As a last resort the record factory replaces anything matching
hmcp_[A-Za-z0-9_-]{16,}with[REDACTED:mcp_token](horae.secrets.logs.MCP_TOKEN_SHAPE): a token a client sent is not a secret this process resolved, so value-based redaction cannot know it.listshows name, scopes, times and status, never a token or a digest. Refusals are logged without detail as a count, at most one INFO line a minute (RefusalLog), so a client sending bad tokens cannot flood the log. - G, the listener.
horae mcp serve --http [--host 127.0.0.1] [--port 8765] [--allowed-host NAME]...: stateless streamable HTTP with JSON responses at/mcp(no MCP session, no server-sent stream: each request stands alone). It binds to loopback by default and refuses to start (exit 1,no_token) while no token is usable (none, all revoked or expired). A non-loopback--hostprints a warning: the token travels in clear text unless a TLS reverse proxy terminates in front. The SDK's DNS-rebinding check is always on:Hostmust be a loopback name or an--allowed-host(any port), and anOrigin, when sent, one of them.--host,--portand--allowed-hostwithout--httpare a usage error. SIGINT / SIGTERM stop it (exit 0; a second signal forces). - H, not done here. No rate limit: a 256-bit token cannot be guessed, and a client
flooding refusals costs one store read each (loopback by default; a proxy can limit). No
TLS in Horae (a reverse proxy's job, as for
horae serve). No token rotation command: create a new one, switch the client, revoke the old one. The plain-HTTPhorae serveAPI keeps relying on the SSO proxy (decision 51); this decision is the MCP server's.
- A, tokens.
Provisional decisions (#50, pending maintainer review)¶
- The egress allow-list proxy of plugin containers (#50). No schema changes: the policy is
the lock's existing
permissions.networkandpermissions.network_local, and blocked attempts use the existingegress_blockedviolation kind of the run record. The code is inhorae.plugins.host.egress_proxy(the proxy, standard library only) andhorae.plugins.host.egress(starting it, reading its reports). The operator guide is docs/operations/plugin-containers.md. Onlyruntime: container(decision 74) has a proxy. The process runtime is unchanged (it has no isolation, T05).- A, implementation: a small asyncio proxy in Horae, run in its own container. It is
about 500 lines with no dependency. The core passes its source to the image's
interpreter (
python3 -I -S -c <source> <policy JSON>), so it runs from the digest-pinned image the plugin already uses (decision 74 G), with no extra image to build, pin or pull. The tests import the same module. An off-the-shelf proxy (tinyproxy, squid, Envoy) was rejected because none of them resolves a name once, checks every answer against private, loopback, link-local and metadata ranges, and connects to the checked address. Each would also add an image to pin and a configuration generator, so the policy would live in two places. - B, one proxy per plugin start.
ContainerRuntime.spawnstarts the proxy before the plugin and waits for itsreadyline (30 s). The container isdocker run --interactive --rm --init --pull never --log-driver none --user 65534:65534 --read-only --cap-drop ALL --security-opt no-new-privileges --pids-limit 64 --memory 128m --sysctl net.ipv4.ip_forward=0 --label dev.horae.egress-proxy=<plugin> --network horae-plugin-<plugin> --network horae-egress. That is decision 74 C's hardening; the proxy runs asnobodybecause it reads no file, has no mount at all, and never forwards packets between its two networks. The policy argument is built from the plugin's locked lists only, so no plugin can use another's allow-list. It also carries the plugin network's subnet: the proxy listens on port 3128 of its own address on that network only (never onhorae-egress), and serves only the client admitted in C.horae-egressis created on first use: a bridge that is not--internal, labelleddev.horae.network=egress, withenable_icc=falseand no IPv6. Each run checks it like a plugin network: noConfigOnly/ConfigFrom, and every attached container must carrydev.horae.egress-proxy. A network of that name that fails the check is refused, never repaired. Itsenable_icc=falseis defence in depth only: it was not enforced on OrbStack's engine (containers on an ICC-off bridge reached each other), so the proxy's own listening address and client check are the real barrier. Docker 25 or later is needed, becausedocker runtakes two--networkflags. - C, amendment to decision 74 D. A plugin network now has
enable_icc=true, because the plugin must reach its proxy on that bridge. It keeps--internalandinhibit_ipv4, so the host still has no address there. Only the plugin's own containers (dev.horae.plugin=<name>) and its own proxy (dev.horae.egress-proxy=<name>; the value is now checked, where before any value passed) may be attached. #49's networks (enable_icc=false) are refused with "remove it" and recreated on the next run. Each proxy serves one container. Two concurrent runs of one plugin share its network, so without more a run's plugin could use the other run's proxy (and its lock, if it changed in between). Once the plugin's container has started and finished its handshake, the host reads its address on the plugin network (docker container inspect) and writes it to the proxy's stdin ({"client": "<address>"}); the proxy admits that one address (once, and only inside the plugin network's subnet), confirms (admitted, within 10 s, else the plugin is stopped:runtime_unavailable), and drops every other connection without an answer, including any before the admission. Chosen over the alternatives: a fixed--ipfor the plugin needs subnets Horae picks itself (Docker refuses--ipon a network whose subnet it allocated), with collisions between runs to handle; a network per plugin start adds about 0.4 s per start and leaks a subnet of Docker's limited address pool whenever Horae is killed before removing it. The admission keeps one network per plugin and binds the proxy to exactly one container. A plugin cannot connect out before its handshake is done. - D, the plugin's environment.
HTTPS_PROXY,HTTP_PROXY,https_proxy,http_proxyandHORAE_EGRESS_PROXYall holdhttp://<proxy IPv4 on the plugin network>:3128, read fromdocker container inspectonce the proxy is ready. They are set by the core in the secret-free part of the environment (horae.plugins.host.env.PROXY_KEYS).*_PROXYandHORAE_*stay on the secret deny list, so a plugin cannot override them, andNO_PROXYis never set. This replaces decision 66 F in two ways. The standard variables are set too, so clients that read the environment (urllib,requests,httpxby default) work unchanged. And local grants also go through the proxy instead of per-grant routes, which would need privileges (iptables in the plugin's namespace) that Horae does not have. A client withtrust_env=Falseignores the variables: it has no route, so it fails closed. horae-sdk 0.8 addsegress_proxy()to pass the proxy explicitly. Other protocols (IMAP) must tunnel withCONNECT. - E, the policy. Each connection carries one request:
CONNECT host:portto anetworkhost is allowed on port 443 only. Decision 10 accepted any port, but the lock has no port syntax for public hosts, so the proxy caps it. A port syntax would be a later, compatible change.CONNECTor an absolute-form plain-HTTP request is allowed to an exactnetwork_localhost:port. Plain HTTP is never allowed to a public host (decision 66 C). It is forwarded in origin form withConnection: close, and theProxy-*,Connection,Keep-Alive,TE,TrailerandUpgradeheaders are dropped.- An IP literal is allowed only when it is exactly a local grant (canonical form; IPv6
in brackets). Every other literal is refused, including the legacy numeric forms the C
resolver reads as addresses (
127.1,0x7f000001). - Names are lowercased and must be plain DNS names with no trailing dot.
- The proxy resolves the name itself. Every answer must pass: for a public name,
globally routable (not private, CGNAT, documentation, multicast or site-local
fec0::/10), and never an IPv6 address carrying an IPv4 one (IPv4-mapped, IPv4-compatible, NAT64, 6to4:embedded_address); for a local name, in decision 66 B's private ranges, never link-local (169.254.0.0/16, fe80::/10:link_local_address), which only an explicit IP-literal grant reaches. Metadata addresses (decision 66 B's and Azure's 168.63.129.16, a public address) and loopback (the proxy's own container) are always refused. One bad answer refuses the whole request, so a resolver mixing answers gets nothing. - The connection then goes to the first IPv4 answer, an address, never the name again, so DNS rebinding cannot change what was checked. Each new connection resolves again and is checked again.
- No TLS interception. Bounds: an 8 KiB head read within 10 s, DNS and connect timeouts of 10 s, 300 s idle per tunnel, 64 connections.
- Refusals answer
403with the reason code. A name that does not resolve or an unreachable upstream answers502, and so does an answer with no IPv4 address, becausehorae-egresshas no IPv6. - F, blocked attempts. The proxy writes one JSON line to stdout per refusal:
{"event": "blocked", "host", "port", "reason"}, wherereasonis a fixed code. Policy refusals (403):host_not_allowed,ip_literal,port_not_allowed,plain_http_not_allowed,private_address,embedded_address,link_local_address,loopback_address,metadata_address,not_local_address. Targets it cannot parse (400:127.1, hex or octal forms, user info, a trailing dot, anhttps://absolute form):malformed_target, with an empty host and port 0, so nothing the plugin wrote is repeated. Resolution failures (502):dns_failed,no_ipv4_address. It never writes a URL, path, query, header or body. It lists at most 200 per minute; what the cap hides is counted and reported as{"event": "suppressed", "count": N}every second while the count is not zero, so a flood of junk requests cannot silence later attempts. The host reads the lines (ProxyHandle.watch), checks them again (host shape, port range, reason shape), logs each at WARNING and keeps them (capped) until the end of the next call. They then becomeegress_blockedviolations,<plugin>: egress blocked to <host>:<port> (<reason>)(egress refused, unreadable target (malformed_target)without a host), plus one<plugin>: N more blocked egress attemptson each call during which suppressed counts arrived, redacted like any message, since a refused name can carry a secret. They attach to the call'sToolResultor, if the call fails, to itsToolCallError.violations, which the engine now records too. They appear in the run record'sviolations(their kinds inhorae run --json) and the log. Attempts reported after a plugin's last call are only logged. - G, stop. After the plugin's container is removed, its proxy's stdin is closed (the
proxy exits), its CLI is killed if still there, and
docker rm --forcealways runs, bounded. The proxy's attachment tohorae-egressgoes with it, and the network itself is kept for the next run. - H, fail closed. If the proxy cannot start (the CLI or image fails, it has no address
on the plugin network, or
horae-egressis not as in B), the proxy is removed and the plugin is not started (runtime_unavailable); if it cannot be bound to the plugin's container (C), both are stopped and removed. A proxy that dies during the run leaves the plugin with no route at all. - I, limits. A
network_localgrant on loopback (127.0.0.1:1143, Proton Mail Bridge on the Docker host) is refused (loopback_address): loopback in the proxy is its own container. Reaching a service on the host needs a grant of the host's address on the LAN, or a host-gateway route (a follow-up). A Docker service name declared innetworkresolves to a private address and is refused. A link-local service (169.254.x.y) is reachable only through a literal grant of its address. A blocked attempt that never reaches the proxy (a direct connection) is not recorded: it fails with "network unreachable". The proxy limits where a plugin connects, not what it sends there: an approved host can still receive the plugin's data (T05).
- A, implementation: a small asyncio proxy in Horae, run in its own container. It is
about 500 lines with no dependency. The core passes its source to the image's
interpreter (
Provisional decisions (#55, pending maintainer review)¶
- Approval-gated
pipeline.run(#55). One new MCP tool,pipeline.run, a store migration (10:approvals,approval_events), a new result contract (schemas/mcp/pipeline-run/v1.json) and a new command group,horae approval list|show|approve|deny|revoke(horae.approval,horae.cli_approval). Decision 76 is taken by #50, in parallel.- A, the tool only asks.
pipeline.run {pipeline}needs the scopepipeline.run(decision 75 C; granted over stdio, decision 75 B). It runs the pipeline as a dry run (Runner.run(dry_run=True): the engine applies nothing either way, and no sink is asked to apply; collect steps and the LLM run as inhorae run --dry-run, charged to the daily budgets), plans it (plan_changes, which only callsSink.read) and returns a summary of what would be applied (counts and one line per change: kind, action, a clippedx-untrustedtarget; never a note body, a diff, a notification text or an HTTP body) and, when there is something applicable, an approval id with its expiry. It takes no template variables, path or command: what runs is the pipeline as configured. A run that failed, a plan with problems or refused, or an empty plan get no approval (reason). - B, the approval channel is the CLI, on a terminal.
horae approval approve <id>is run by the user on the instance. It re-plans, shows the whole change set (ashorae diff, HTTP bodies in full; when a note change is binary or larger than 1 MiB and so cannot be shown, it refuses,not_reviewable, and the approval stays pending) and asks the user to retype a short code printed with it (the last 6 characters of the binding digest;ydoes not do). Without a TTY on stdin it refuses (not_interactive); there is no--yes. Why the CLI: the MCP server must never be able to approve, so the approval travels a channel an MCP client cannot reach through MCP: a token holder over HTTP and an MCP-only stdio client have no way to run a command on the instance. What it does not stop: an agent that also has a shell as the same user (Claude Code's Bash tool, say) can allocate a pseudo-terminal (pty.fork(),script,expect), read the code and type it; the review reproduced this. The TTY check and the code are friction against approving by accident or by habit, not a boundary; such an agent can already runhorae runitself (decision 75 B). Do not give one client both this MCP server and a shell as you if you rely on the approval. ntfy action buttons (/act, decision 54) were rejected for now: an/actlink is a bearer capability that reaches the phone through a third-party push service, it would put a state-changing approval behind one tap with a small screen for the diff, and/actintents are fixed task actions, not an arbitrary run's plan. The API behind the SSO proxy was rejected becausehorae serveis optional and has no write route today. Both remain possible later, on top of the same store transitions. The MCP server registers no approve, deny or revoke tool; it imports onlyrequest_dry_run, and the approving transitions (approval_claim,approval_decide,approval_finish,Runner.apply_planned) are not referenced fromhorae.mcp_server. - C, what an approval is bound to. The approval row keeps a binding digest,
SHA-256 of the canonical JSON of: the pipeline name; the pipeline's digest, the instance's
config_digestandlock_digest; the run context (date, time zone, variables) and the run'sinput_hash; every proposed intent with its route; and the planned change set (horae.apply.to_dictwithout the run id, the dry-run flag and the notification dedupe keys, which depend on the run id): note paths with before and after SHA-256 and the diff, task changes, notifications (with whether each was already sent), HTTP calls. At request time the digests are the dry run's own; at approval time they are the current instance's. Applying does not run the pipeline again: the dry run's record is copied into a new run (new id, not a dry run, no LLM calls or cost of its own) whose intents are re-planned against the vault under the apply lock, and the change set is applied only if the recomputed digest equals the approved one (hmac.compare_digest); otherwise the run is savedfailed(approval_mismatch, nothing applied) and the approval isrefused. A changed note, pipeline, plugin set, model configuration or lockfile, a notification sent meanwhile, or a task that changed in the index therefore all refuse. The apply itself is the normal one (journal first, compare-and-swap on note bytes), sohorae undo <run>reverts it like any run. - D, lifetime. An approval is
pendingfor a TTL set by the server,horae mcp serve --approval-ttl MINUTES(1 to 60, default 15). Statuses:planning(the dry run is running),pending,approving(claimed, the apply is running), and the finalapplied,failed(the apply failed),refused(binding mismatch),denied(horae approval deny <id>),revoked(horae approval revoke --all, or the requesting token was revoked:horae mcp token revokemoves its pending approvals torevokedin the same transaction, and the claim also requires the token not to be revoked),expired(seen past its TTL) andvoid(the dry run gave nothing to approve). Onlypendingcan be approved, denied or revoked. - E, single use. Approving first claims the row with one compare-and-set
(
UPDATE … SET status = 'approving' WHERE id = ? AND status = 'pending' AND expires_at > now ANDthe requesting token, if any, is not revoked), taken with the pipeline lock held: two concurrent approvals of one id apply once; the loser is told the current status. The run that applies it is recorded on the row as soon as it begins. Interruptions: a cancellation (a signal) during the apply lets the shielded apply finish and save its run; the approval then ends from that record (appliedforok,noop,degraded, elsefailedorrefused), andfailed"interrupted" only when no record was saved. A crash leavesapproving(never re-applied); it is settled under the pipeline lock (on the next approval of that pipeline, or bylist,showandapprovewhen the lock is free): the dead run is recovered, then the approval ends from its record, orfailed"interrupted" when there is none (horae undoreverts what an abandoned run wrote). - F, journal. Every transition appends a row to
approval_events(approval, time, event, run id, short reason) in the same transaction as the status change;horae approval show <id>prints them,listshows the latest status, the dry run and the applied run. The applied run is an ordinary run inhorae runsand the apply journal. - G, flood limits. Per requester (a token's id, or
stdio), at most 3 approvalsplanningorpendingat once and at most 12 requests per rolling hour; above that the tool error istoo_many_pending/rate_limitedand no dry run starts. The check and the insert of theplanningrow are one transaction. - H, not done here. No approval over ntfy or the HTTP API (B); no template variables
from the client; approvals are not shown in
runs.recentor/runs(the run view keeps its contract; the approval log ishorae approval list).
- A, the tool only asks.
Provisional decisions (#51, pending maintainer review)¶
- Declared mounts and resource limits of plugin containers (#51). One additive schema
change to
instance/v1.json:plugin_defaults.limits,plugins.<name>.limitsandcontainer.mount_roots. One new host error kind,oom_killed. Code inhorae.plugins.host.mounts(the mount plan and the sweep) andrun_argv(horae.plugins.host.container, still the one place container flags are built); operator guide in docs/operations/plugin-containers.md. Onlyruntime: container(decision 74) changes; the process runtime is unchanged (T04).- A, the same path inside. Each path of the plugin's locked
permissions.paths(decision 70: what the user approved, never the manifest's own) is bind-mounted at the same path in the container:--mount type=bind,source=<path>,target=<path>,bind-recursive=disabledplus,readonlyunless the path is inwrite(writeimplies read; a path in both is writable). The plugin learns where its paths are through the existing configuration channel,_meta["dev.horae/paths"]on every request (decision 35, unchanged): since the paths are the same inside, that list, a pipeline parameter naming a file under them, and a path in a plugin's result all mean the same file on both sides. No environment variable is added.bind-recursive=disabled(Docker 25, already required by decision 76 B): a filesystem mounted below a declared path on the host is not carried in, so it cannot appear, nor stay writable under a read-only mount (kernels before 5.12 have no recursive read-only). - B, what may be mounted. Every declared path is checked before anything starts (the
egress proxy included); one refused path refuses the plugin,
runtime_unavailablenaming the path and why (fail closed, decision 74 H). In order: --mountmust carry it: no,,"or control character (as decision 74 H for the plugin directory);- canonical:
realpath(path) == path, so no symbolic link anywhere in it (the host could otherwise be steered by a link a plugin planted in a writable parent, and the container would see the link's target under the declared name). The operator declares the real path; - it exists and is a directory or a regular file (never a socket, device or FIFO: the Docker socket itself is refused here);
- it is, or lies inside, the instance directory or a
container.mount_rootsentry (operator-set inhorae.yaml, default none: a vault outside the instance must be listed there). An entry that is/, Horae's home or an ancestor of it is refused (it is dropped from the roots, and a path under it is refused naming it): list the vault itself; - it neither is, contains nor lies inside a sensitive path, compared in both lexical
and real forms: the instance's
horae.yaml,horae.lock,plugins/,pipelines/,skills/,.git/, itsstate_dirandsecrets.dir; the engine's socket (the context's endpoint) and/var/run/docker.sock,/run/docker.sock,/run/containerd; in Horae's home.ssh,.gnupg,.docker,.aws,.azure,.kube,.config,.local,.netrc,.git-credentials,.pypirc, the shell start-up files.bashrc,.bash_profile,.profile,.zshrc,.zprofile, andLibrary/LaunchAgents,Library/Keychains; macOS's/System,/Library,/Applications; and/bin,/boot,/dev,/etc,/lib*,/proc,/root,/run,/sbin,/sys,/usr,/var/lib/docker,/var/lib/containerd,/var/lock,/var/run, and the container's own/plugin; - it is neither
/tmpnor contains it (it may lie inside it: the bind is mounted over the container's tmpfs); - a writable path is not, nor holds, a git repository: no
.git(in any letter case, since volumes may ignore it) and no git directory layout under any name (a directory holding aHEADtogether with any ofobjects,refs,commondir,gitdir,config,hooks,index,info,packed-refsorworktrees, any case: a bare repository or a linked worktree's directory, whichGIT_DIR, agitdir:file orsafe.bareRepository=allwould use; deliberately broad) as one of its components or anywhere below it (a walk of at most 100 000 entries, which refuses at its bound), and no git directory layout in a directory above it up to its mount root; a plugin could plant hooks the user'sgitruns. It may lie inside a git work tree (the maintainer's choice on #182: an instance kept in git withvault/gitignored, ashorae initlays it out, mounts its vault writable) as long as that repository's git directory stays out of the plugin's reach: for each.gitfound in a directory above it up to its mount root, its git directory (that directory, the one a.gitfile'sgitdir:names, and a linked worktree'scommondir) must neither be nor lie inside any path the plugin is given, read-only or writable, compared by device and inode; a git directory that cannot be told (a.gitfile without agitdir:line, too long, naming nothing, a.gitof another type) refuses the plugin (fail closed); - it does not lie strictly inside a writable path of another container plugin of the
lock: that plugin could swap a directory of it for a link while this one starts. A
writable path also must not be, nor hold, another container plugin's writable
path: no two container plugins write the same tree, so nothing in a container races
a sweep (C). A read-only path that is or holds another's writable one is allowed:
that is how two plugins share data (one writes the vault, the other reads it), and
swapping the declared path itself needs write access to its parent. Process-runtime plugins are not
counted: they run unconfined as Horae's user anyway (T04), so excluding their paths
would refuse common setups (
file-sinkwriting the vault) and protect nothing. The sensitive-path and other-plugin comparisons are made on path strings and on file identities (device and inode of the path, its ancestors and the other path afterrealpath), so another letter case on a case-insensitive volume (the macOS default) or an alias (a link, a bind mount) is recognised; another plugin's writable path that cannot be read refuses the plugin (fail closed). A host built without an instance (tests, tools) refuses every declared path. A plugin in quarantine (C) is refused first. The check is run three times: when the mounts are planned; again right beforedocker run, after the egress proxy has started (mounts.recheck: each path still passes and is the same file, device and inode); and once the container has started and finished its handshake, before its egress proxy admits it (decision 76 C):docker container inspectmust show exactly the plugin directory and the planned bind mounts, each from its own path with its declared access, andrecheckmust pass again; otherwise the plugin is stopped (runtime_unavailable). It has then received its environment (secrets included) but never had a route out. - C, nesting, and what a bind mount cannot do. Mounts are ordered parent first (Docker
orders them by depth too), so each declared path behaves as declared: a writable child of
a read-only parent is writable and the rest of the parent read-only; a read-only child of
a writable parent stays read-only. Docker's
--mount type=bindtakes nonosuid,nodev,noexecornosymfollow: a declared mount has the host filesystem's flags. What holds instead: no capability (--cap-drop ALL: nomknodof a device, nochown, noCAP_FSETID), a non-root user,no-new-privileges(a set-user-ID file never raises privileges inside), and a hard link cannot cross mounts (EXDEV). What a plugin can do in a writable path, and the host must then not trip over: make a symbolic link to anywhere (harmless inside, where it resolves in the container; dangerous to a host process following it), make a FIFO or a socket, set the set-user-ID bit on a file it owns (it is Horae's uid, so on the host that file runs as Horae's user). So once the container is removed,mounts.sweepchecks each writable mount itself and walks it (not following links) and, for each entry whosest_ctimeis at or after the container's start (less 2 s; a plugin cannot setctimeback, so a user's own older files are never touched) and that the plugin could write (not in a read-only child): removes a symbolic link strictly (when in doubt, it goes): any whose target is absolute or has a..component, and any whose resolution by the kernel (realpath, once the container has exited, so chains of links and a..through a linked directory are followed, never read lexically) lands where the plugin could not write itself (outside its writable paths, or in a read-only child of one: a host process following the link would act there for it); removes a device, FIFO or socket; clears a set-user-ID bit (and set-group-ID on a file). It also checks every declared path is still the same file (device and inode) as when it was checked. No race with the sweep: it walks with directory descriptors (each directory opened relative to its parent withO_DIRECTORY|O_NOFOLLOW, listed by descriptor, entrieslstated,readlinked andunlinked relative to it; a file openedO_NOFOLLOW|O_NONBLOCKand checked byfstatto be the objectlstatsaw before itsfchmod); any object that changed in between is a failure. A plugin with a writable path holds a per-plugin run lock (flockon<state_dir>/quarantine/<plugin>.lock) from beforedocker rununtil its sweep is done, so a concurrent run of the same plugin is refused (runtime_unavailable), and B keeps other container plugins out of its writable tree; only writers outside containers (a process plugin, the user) can still race it, and they meet the descriptors. A sweep that never ran: beforedocker runthe host writes<state_dir>/quarantine/<plugin>.pending(O_EXCL,O_NOFOLLOW; failing to write it refuses the start) and removes it only after a clean sweep or a written quarantine; found at a start (taken under the run lock), it quarantines the plugin. A quarantine file that cannot be written leaves the marker, and the plugin is refused for the rest of the run. The quarantine and the marker are checked again once the run lock is held, so a concurrent run that quarantined the plugin in between is seen. The sweep fails closed, and none of its checks swallows an error (each becomes a failure): a new.gitentry (any case), or a git directory layout anywhere in a writable path whatever its age (B refuses to mount one, so it is the plugin's) (the operator guide recommendssafe.bareRepository=explicit), a declared path replaced or removed, a directory it cannot list, an entry it cannotlstator undo, an entry on another device that is not a host mount point (/proc/self/mountinfo; a plugin cannot mount anything, so anything else is unexplained), more than 100 000 entries new since the start or 2 000 000 in all, or a containerdocker rm --forcecould not remove (no sweep at all) quarantines the plugin: a file<state_dir>/quarantine/<plugin>(0600) listing the reasons refuses its next start (runtime_unavailable, naming the file) until the operator has checked the paths and removed it; the runtime also remembers it for the rest of the run. Each finding is logged at WARNING (at most 50 lines a sweep, then a count); like egress attempts after a plugin's last call (decision 76 F), they are not run violations (the call they belong to is over). Residual: a swap of a path component for a link and back between the lastrecheckand the engine's mount, by a writer of a parent directory that is not another container plugin (a process-runtime plugin, the user; a concurrent run of the same plugin now waits for the run lock):docker inspectshows paths, not files, so the post-start check cannot see a swap undone in time (the in-container device and inode differ from the host's on Docker Desktop and OrbStack, so they are not compared); a writable parent can rename the directories between it and a read-only child (the child's contents move along, still read-only, and its host path may then name a directory the plugin made: the sweep reports it); while the plugin runs, what it wrote is on the host as it wrote it. Horae's own host-side writer of notes (horae.apply.local.LocalFileSink, used by the built-in sink andfile-sink) already opens every path component relative to its parent withO_NOFOLLOW(O_DIRECTORYfor directories) and refuses a link anywhere, so it does not follow a link a plugin left during its run either. - D, resource limits. Operator-set in
horae.yamllikeruntime:plugin_defaults.limitsandplugins.<name>.limits, each field of which wins over the default's (the manifest and the lock carry none, so a plugin cannot ask for more). Flags:--cpus,--memorywith--memory-swapequal (no swap),--pids-limit,--ulimit nofile=N:N, and the/tmptmpfssize. Defaults, for a 4-core / 16 GB home server running a handful of plugins (each with its proxy, decision 76 B) at once:cpus: 1.0(one plugin never takes more than a core),memory_mb: 512(ten plugins at their limit still leave over 10 GB),pids: 128(a Python plugin with a thread pool and a few children; a fork loop stops there),tmp_mb: 64(#49's size),nofile: 1024. Bounds in the schema:cpus0.1 to 64,memory_mb64 to 65 536,pids16 to 4096,tmp_mb1 to 1024 and less thanmemory_mb(the tmpfs is charged to the container's memory; pydantic-only rule, checked for the merged limits of everyplugins.<name>),nofile64 to 65 536. Acpusabove the host's CPU count is refused by the engine when the container starts. - E, an out-of-memory kill is reported as such. The plugin container is no longer
--rm: when its process dies during a call or its start, the host reads the container's exit status before removing it: the launcher exits 247 when the plugin died ofSIGKILLwhile the cgroup'smemory.eventsoom_killcount went up (#188; the engine's{{json .State.OOMKilled}}counts too, but the engine can lose that event), and a kill by the memory limit fails the call with the new host error kindoom_killed(plugin <name> (runtime container) was killed by its memory limit (512 MiB, ...)) instead ofplugin_crashedorhandshake_failed; the restart rule is unchanged (one restart a run).docker rm --forcestill always runs once the CLI is gone (decision 74 I); a Horae killed withSIGKILLmay now also leave an exited container: before each start of a plugin, its exited or dead containers (label=dev.horae.plugin=<name>) are removed withdocker rm(never--force, never a running one). A concurrent run's container that has just exited may go with them, and its kill is then reported as a crash. A PID-limit hit is not a kill: the plugin'sforkfails (EAGAIN) and the plugin reports it. CPU is throttled, never killed. - F, left to #52. The malicious-plugin suite exercises these: an undeclared path, a
write to a read-only path, an escaping link, a fork bomb, a memory hog. Threat rows T51
to T53 of
docs/security.md.horae doctordoes not check mounts yet (a follow-up): the first run reports them.
- A, the same path inside. Each path of the plugin's locked
Provisional decisions (#191, pending maintainer review)¶
- Third-party and direct installs only under
runtime: container(#191). The maintainer chose the policy: lift both gates of decisions 70 E and 71 B, but only for plugins that run in a container (decisions 74, 76, 78). One additive schema change:lockfile/v1.jsongainsplugins.<name>.tierandplugins.<name>.index(B). One new host error kind,runtime_refused(C). Threat rows T04, T05 and T20 ofdocs/security.md.- A, the install gate. "First-party" is unchanged: tier
first-partyclaimed by an index ofFIRST_PARTY_INDEXES(the default Horae marketplace). A first-party plugin installs and runs under either runtime. Anything else (acommunitytier,first-partyclaimed by an index the user added, a direct install from a git URL) installs only when its effective runtime inhorae.yamliscontainer:plugins.<name>.runtime, elseplugin_defaults.runtime(InstanceConfig.plugin_runtime). Otherwisetier_refused(exit 3), saying how to enable it: setplugins.<name>.runtime: container(or the default) and make sure Docker is available.require_installable(name, tier, index, runtime=...)is the one check for every source, andapproval.DIRECT_INSTALLSis removed (the runtime is the one switch, nothing can drift). A marketplace plugin is checked before anything is fetched. A direct install's name is known only from itsplugin.yaml: it is refused before anything is fetched whenhorae.yamlruns no plugin in a container, then checked again (the firstpreparestep, before the approval and the venv) with the name. To makeplugins.<name>.runtimesettable before the install,horae plugin addloads the instance withinstalling=True: a plugin configured inhorae.yamlbut not inhorae.lockyet is not a problem there (only there; every other command still reports it). Configuring it also enables it, as for any plugin. - B, the lock records the trust.
LockedPlugin.tierandLockedPlugin.indexare set, together, for a marketplace plugin that is not first-party, and absent for a first-party one, so every lock written before stays byte-identical and valid; a direct install keepssource: directand has neither (a validator refusestierwithoutindex, either without the other, and either withsource).LockedPlugin.first_partyis "nosourceand notier". The lock, not the install record, because it is what the user reviews, commits and approves, and what--yescompares (lock_mismatchrefuses a different tier or index). Absent means first-party because, before this decision, the tier gate let only first-party marketplace plugins write an entry withoutsource. - C, the run-time gate.
HostRegistrymarks each plugin first-party or not from its lock entry, never from the manifest. The install record (.horae-install.json) can only take first-party away: a record sayingsource: direct, or a tier and index that are not first-party, makes the plugin not first-party whatever the lock says (a lock edited or written by an older core); a record that says nothing (none, or written before it recorded the tier) leaves the lock's answer. So a lock entry without the information and without a record (the built-in plugins ofhorae init, a plugin copied by hand, decision 70 F) is first-party: the operator put it there.PluginHostrefuses to start a plugin that is not first-party unless its effective runtime iscontainer, as the first thing of a start: before any secret is resolved for it or written, before any process or container. The new host error kind isruntime_refused(a start failure: the plugin is unavailable for the rest of the run, and a dry run with it as a sink exits 1). This holds whenhorae.yamlis changed after the install. Never a fallback. - D, approval. The prompt starts with the plugin's source (marketplace or direct, with
the repository), its tier and index, and either "runs in a container (runtime:
container)" or, for a first-party plugin, the runtime it will use.
add --jsonreportsfirst_party,runtimeandenabled(a plugin configured before the install is enabled at once). - E, upgrade. The gate applies again with the instance's runtime: a plugin whose index
no longer says
first-partyneedscontainer. The permission diff has atieritem (~ first-party (Horae marketplace) -> community (<index>)) that widens when the new entry is not first-party, so--yesrefuses it. A direct install can now be upgraded:horae plugin upgrade https://<host>/<owner>/<repo>@<full sha>. The URL must be therepoof exactly onesource: directentry (compared as written; never repeated in a message), the tree must hold a direct install's record, the gate must pass, and the commit is fetched asadddoes (decision 71 C: reachable from the repository's own branches or tags, never fetched by its id) and placed in a staging directory (install_commit(..., replace=NAME)); itsplugin.yamlmust name the same plugin, and a lower version needs--allow-downgrade. Then the same diff, approval, swap and rollback as decision 73 F.--preand--offlineare usage errors with a URL; a name given for a direct install points toupgrade URL@SHAor remove then add. - F, audit and remove.
auditreportsfirst_partyandruntimeper plugin (as the host decides them) and the new drift kindruntime_not_container: a plugin that is not first-party whose effective runtime is notcontainer(the host will refuse it). Thetierandindexcolumns fall back to the lock's when there is no record.removeneeds nothing new. - G, no build for a plugin that is not first-party (security review of this PR). A
build backend on the allow-list of decision 69 B still runs plugin code on the host as
the Horae user (
setup.pyunder setuptools, a hatch build hook,pdm_build.py): fine for first-party code, arbitrary code execution outside the container for anything else. SoPluginEnvironment(install_project=False)(chosen bycli_plugin.environment_forfor every plugin that is not first-party, ataddandupgrade):uv sync --locked --no-dev --no-install-project --no-build --no-build-package=<each dependency>installs the dependencies only, from their hashed wheels, and uv refuses to build anything at all.check_projectalso refuses, before uv runs,[project] dynamic(verified: with dynamic metadata uv calls the backend even with--no-install-project), atool.uv.workspace, anytool.uv.sourcesentry that is not an index (path, git, url, workspace, editable), and a direct reference (name @ ...) in the dependencies, optional dependencies or dependency groups;backend-pathstays refused, and the lock must still list nothing but hashed index or URL packages besides the root project (check_lock: path, git, directory, editable and virtual sources refused). Tested with a path dependency whosesetup.pywould write a marker: refused, never written. Horae then writessite-packages/_horae_plugin.pth(created exclusively, a dependency shipping that name is refused) naming/plugin/srcwhen the tree has a realsrc/directory (lstat, never through a symlink), else/plugin: the path the container sees (the plugin's mount, decision 74 C), which is the only place such a plugin runs (C). Without an installed project there is no console script, soruntime.command[0]must be the venv'spythonorpython3([python, -m, <module>]); anything else is refused (install_refused) by the firstpreparestep, before approval. The prompt says "installed without running its build". First-party plugins are built and installed as before. Tested with a setuptoolssetup.pyand a hatch custom hook that would each write a marker: none is written. - H, trust classes never share uv's cache (independent review of this PR). The review
reproduced a poisoning: a third-party
uv.locklistsflit-coreunder the real index but with its wheel URL on the attacker's host and the attacker's hash; uv fetched it and cached it under the index, and the next first-party build, whose backend uv resolves without hashes, imported it on the host. Fixed twice over: (1) a plugin that is not first-party installs (and upgrades) with its own uv cache, inside the install's temporary home and deleted with it;<state_dir>/uv-cacheis for first-party installs only. (2)check_lock, for every plugin, requires each file of a registry package to be served by that registry's host over https (same host and port), or by its known files host (pypi.orgserves fromfiles.pythonhosted.org/packages/...), or to lie inside a local directory index: no other host, nohttp, no credentials, query or fragment. For a plugin that is not first-party the registry itself must be the default index (https://pypi.org/simple) and aurlsource is refused, so a third-party lock cannot make the host fetch an arbitrary URL (the review's SSRF finding). Existing first-party locks from PyPI pass unchanged. A regression test serves a good and an evilflit-corewheel of the same file name from two local HTTP servers, installs a third-party tree then builds a first-party one on the same instance: with the host check removed, only the private cache keeps the marker from being written (and without it, it is written). (3) Hash-pinned build requirements for first-party builds were not done:uv synchas no--build-constraints(onlyuv pipanduv builddo), andtool.uv.build-constraint-dependenciesis plugin-controlled and takes no hashes; a Horae-maintained, hashed set for the five allowed backends and their own dependencies, per Python version, is a follow-up. Until then a first-party build trusts the index over https for its backend, as decision 69 B already says. - I, what this does not do. It does not make a container safe by itself: the guarantees
and gaps of decisions 74, 76 and 78 (egress through the proxy only, declared mounts, the
limits, the Docker socket of T26) are what a third-party plugin is confined by. Horae in
the published image still cannot start containers (decision 74 J): there a third-party
plugin installs once
horae.yamlsayscontainer, but failsruntime_unavailableuntil the operator gives Horae an engine.horae doctor(#194) reports each plugin that is not first-party (as the host decides it) whose effective runtime is notcontainer, with the same check asaudit(audit.runtime_drift), and, when a plugin runs in a container, a missing or unusable local Docker engine (container.engine_problem: the CLI, a localunix://DOCKER_HOSTand context, a daemon that answers; nothing is started or pulled). Both are errors, as every doctor problem that makes a run fail. An end-to-end test (tests/test_plugin_nobuild_container.py, markedmalicious,containerandlive) installs a synthetic third-party plugin without building it, with its venv made inside the plugin image, and makes one real tool call underruntime: container: the.pthmakespython -m <module>importable at/plugin/srcand nosetup.pyor build hook runs.
- A, the install gate. "First-party" is unchanged: tier