Changelog¶
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
From 0.15.2 on, every merge to main is a release, and this file no longer
grows. Each PR adds a fragment to changelog.d/, and
each version's notes are on its
GitHub Release. The
history below runs up to 0.15.1.
[0.15.1] - 2026-10-12¶
A patch release: 0.15.0's zeocore command didn't run on a plain install.
It also closes the unprotected TestPyPI publish target.
0.15.1 has no tag. It was published from e22a16ca by Publish run
38201406179, a manual dispatch, before release on merge. Its smoke test failed
on index lag 30 s after the upload, so that run made no GitHub Release. The
files on PyPI carry GitHub attestations for zeroemployeeorg/zeocore,
publish.yml and pypi, and install and run on a plain install.
Fixed¶
- The
zeocorecommand runs on a plain install. In 0.15.0 it crashed at start-up onpip install zeocore:rfc8785, which the canonical digest needs, was only in theruntime-hostextra, and loadingzeocore releasepulled inrequeststhroughzeo_core.integrations.github, which only thegithubextra installs. The import check in the publish smoke test passed, because it never ran the command. Now: rfc8785is a base dependency;zeocore releaseloads only when it is used, and on an install without thegithubextra it answersextra_missing(exit 20), naming the extra;- a test runs the command with every extra-only module refused;
- the publish smoke test runs
zeocore versionon the plain install, before it adds any extra.
The workaround for 0.15.0 is pip install 'zeocore[runtime-host,github]==0.15.0'.
Changed¶
- Every publish goes through the protected
pypienvironment.publish.ymlno longer has atestpypidispatch target, its job or its smoke step. That environment had no protection, so any account or App able to dispatch the workflow could publish to TestPyPI unreviewed (ZEOCORE-SOW-30 §3.2). A test now pins the dispatch options topypiand the workflow's environments topypialone.CONTRIBUTING.md's release steps drop TestPyPI staging, say the operator tags, and namezeroemployeeorgas the trusted publisher's owner.
[0.15.0] - 2026-10-12¶
This release ships every change since 0.12.0. Three planned releases were never published, and their changes ship together here: 0.13.0, 0.14.0, and the binding-fence release, which was planned as "0.15.0 or 0.16.0". No entry below was changed by folding them.
It conforms to these ZEOconnect Broker contracts, each pinned from its merge
commit:
- 1.0.0: zeoconnect #35 at 2475934682ca07d480aa16946b3f3d6647255f6f,
file sha256 39e97d170941c4fba95f018b3943715fc0b7aa916211e1c1b28582e52366b2c0;
- 1.2.0, the expected-binding fence: zeoconnect 31da8bda (#56),
docs/contract/broker-contract-v1.md, sha256 d2be4901…;
- 1.2.1, the changed-request marker: zeoconnect 707bb91b (#67),
contract/broker-contract-v1.md, sha256 dc2e951f…;
- 1.2.2, the re-enrolment code: zeoconnect 243409bc (#70),
contract/broker-contract-v1.md, sha256 358bcb0f…;
- 1.4.0, the access refusals: zeoconnect c134661e (#73),
contract/broker-contract-v1.md, sha256 15f7b4db….
Added¶
- The expected-binding fence (contract 1.2.0 §6a). A fenced invocation is refused when its connection was re-enrolled or changed between the listing and the call.
HostedConnectionSummary.connection_revisionis the enrolment's revision.summary.expected_binding()returns aHostedExpectedBindingforHostedOperationRequest.expect.- The Broker refuses a mismatch with no further provider call.
binding_mismatch_of(response)names the field that differed, andreceipt["binding"]holds the values the Broker found. - When the fence can't be checked, because the listing has no revision or
the Broker answers a fenced call with 422, zeocore raises
HostedFenceUnsupportedError. Itsreasonsays which:"no_revision"or"invalid_fenced_request". A 1.2 Broker answers invalid arguments with the same 422, so the second message does not claim the fence alone was the cause. zeocore never resends the request unfenced. - Every request now declares
ZEOconnect-Capabilities: stopped-code, expected-binding. - A re-enrolled connection is its own error. A connection id re-enrolled
with a changed subject, scopes, resources or credential is refused by the
Broker with a 400
kernel connection binding changed(zeoconnect #59). This now raisesHostedConnectionChangedErrorinstead of a generic refusal. It comes before any provider call, and the fix is ZEOconnect's repair, never a retry. From contract 1.2.2 the Broker also marks it"code": "connection_binding_changed"for a client declaringexpected-binding. zeocore reads the code first and keeps the detail string as the fallback, so a 1.2.1 Broker is still recognised. -
A changed request under a used key is its own error (contract 1.2.1 §6a.5). The same idempotency key with different arguments or a different
expectis refused, nothing is recorded, and the key's original outcome stands. An effect's marked 400 raisesHostedRequestChangedError. A read comes backfailed_safe, whichrequest_changed_of(response)recognises. The fix is a new key for the changed request, never a retry. An unmarked conflict, such as the 1.1approval is unavailable, stays a plain refusal. -
HostedRevolutBusinessClient: Revolut Business account and transaction reads through ZEOconnect, read-only (contract §6). On the wire the query's start field isfrom; a result carrying any JSON number is refused, so amounts are only ever exact decimal strings. HostedStoppedError(withcontrolandscope),HostedUnavailableError,HostedUnreachableErrorandHostedUpgradeRequiredError, all subclasses ofHostedClientError, andstop_of(response)for an orchestrated stop.NormalizedErrorCode.STOPPED. zeocore declaresZEOconnect-Capabilities: stopped-codeon every request, so the Broker may send it; without that capability it sendsREQUEST_REFUSEDwithstopped:<control>:<scope>, whichstop_ofreads the same way.TransactionQueryacceptsfromas well asfrom_.-
Contract
1.1.0additions (zeoconnect #40), which are additive, so no re-pin is needed:HostedOperationResponse.replayedis true when the Broker served its stored outcome, which is never a fresh success.is_outage(response)recognizesfailed_safewithPROVIDER_UNAVAILABLE, such ascontrols_unavailable:<control>, as an outage, never a stop. The Broker stores that outcome, so retrying with the same idempotency key replays it; another attempt needs a new key and is a new occurrence, never an automatic retry. YouTube retention defers on it. -
A named session file for a product's service user (operator ruling, 2026-10-12; client-access proposal §9, option A).
ZEOCORE_SESSION_FILEselectsFileSecureSessionStore. It is opt-in, never a fallback, and checks: - a 0700 directory owned by the user, with no symbolic link in the path;
- no directory above it writable by another user unless it is sticky;
- a regular 0600 file owned by the user, checked on the open descriptor.
Writes are atomic, and the file is bound to its Broker origin. Without the variable, a Keychain that can't be read still fails closed with exit 12.
- Broker contract 1.4.0 (zeoconnect #73, merged at
c134661e): - the three access refusals:
door_required,app_identity_unverifiedandno_principal, in both of their forms (an:invokeansweredfailed_safewith the exact message, and 403{"code": ...}elsewhere). The client raisesHostedAccessRefusedErroror reportsaccess_refusal_of(...), and the CLI answers each by name with the way back; - clearer CLI answers: a stop answers its
controlandscope, and a 426 answersupgrade_required; -
the parity fixtures for ZEO-RT's door (ZEOCORE-SOW-27 §3), in
contracts/broker-1.4/: digest vectors for one request per 1.4.0 operation, pluson_behalf_ofvariants, each validated against the frozen schemas, with zeoconnect's own conformance cases vendored beside them.tools/broker-1.4-digest-vectors.pyrewrites them. -
Delegated PyPI releases (
zeocore release pypi apply | approve), on the operator's delegation of 2026-10-11. - The
zeo-releaseGitHub App creates the release tag with a one-repository token minted from its Keychain key. - matorclawson approves the waiting
pypideployment, once, only for that exact tag and commit. admitrefuses unless only the two identities, together, can release: matorclawson is the only reviewer with self-review prevented and no admin bypass, onlyv*tags deploy, and a tag ruleset lets only the App touchv*.-
The targets are a reviewed table: zeocore, zeocreator, zero-employee and sovereign-agent.
-
The PyPI adapter (
zeocore release pypi plan | admit | apply | reconcile | verify), on ZEOCORE-SOW-26. planchecks the commit is reviewed and the version agrees everywhere.admitchecks that only the operator can approve the publish: the tag's creator can't approve its own deployment or bypass it as an admin, and onlyv*tags may deploy.applycreates the release tag, its one effect, under a durable intent, and never retries.reconcilefollows the tag to its publish run.-
verifychecks PyPI's files, each attestation's recorded publisher, and that each attestation names that file's digest. -
One sign-and-verify step for every org executable (
zeo_core.release.signing,zeocore release sign | verify), on ZEOCORE-SOW-19 to SOW-22. It is built first, before the PyPI adapter, because the Go seats and Pomar wait on it. - Internal Darwin releases sign with ZEO Runtime Code Signing, pinned by its
leaf SHA-1. Distributed releases hold as
notarisation_unbuilt; Linux is refused as signed until a Linux contract is adopted. - Inputs come from the reviewed
release.yaml, never from flags. The signing host is configuration (ZEOCORE_SIGNING_HOST). - A separate candidate is signed under a durable intent, and a lost answer is reconciled by readback, never by signing again.
verifyis read-only. It refuses an ad-hoc signature even when its requirement names the pin, a bare cdhash, another certificate (including the other audience's), and entitlements that differ from the manifest's.- A locked keychain is reported only when its settings establish it.
- Request and response packs (
zeocore release pack | receive) for signing on matormini from another host. -
The signing service on matormini (
zeocore release serve) and its client (zeocore release send). It is tailnet-only and identifies callers bytailscale whois. It admits a request only under ZEOCORE-SOW-24 §1: a node, product and identifier allowlist; the manifest read from GitHub at a merged commit; internal audience only; size, count and rate bounds; and a durable journal of every request. -
Revolut Business reads for expenses, receipts and labels (
zeo_core.integrations.revolut), approved by the zeocore elders as an independent 0.13.0 expansion (org issue #787, Q2): list_expenses(one bounded page, withnext_toand stall detection);get_expense;download_receipt, bounded to 10 MiB while it is read, never parsed or logged, and returned with its sha256;list_label_groupsandlist_labels, which page by an opaque token.
Amounts stay exact Decimals, and an expense's payer name is dropped.
Redirects are never followed. A provider identifier must be one safe path
segment, or nothing is sent. The 0.12 read operations and their error codes
are unchanged.
Offline contract only; no request has been made to Revolut. Which date
Revolut's expense window filters on is not stated in its published
contract. The cursor assumes expense_date, and that is unverified until a
live sandbox run. So every ExpensePage reports
completeness="unverified", and a run that reaches next_to=None is not
proof of a complete window (org #787, council ruling on E4).
- The zeocore command, for callers that don't import Python: the ZEOconnect
Broker and WEB, TypeScript pipelines, scripts. JSON on stdin and JSON lines on
stdout with the result last. Exit codes are the YouTube publish command's
family: 0, 2, 10, 11, 20, plus 12 not paired and 13 ambiguous
(docs/reference/cli.md).
- zeocore schema list and zeocore schema <name> give the public contract
models as JSON Schema 2020-12 under stable names, among them
hosted.operation-request, hosted.operation-response and
connections.normalized-error. The same schemas are committed under
contracts/zeocore-v1/, and a test fails if a model drifts from its file.
- zeocore validate <name> checks a value and answers the normalized form.
Its errors carry location and type only, never input values.
- zeocore digest is the sha256 of a value's RFC 8785 canonical bytes.
- zeocore version names the release and the protocols.
- The ZEOconnect client as zeocore commands, so apps in any language reach
the Broker through one client instead of writing their own: login, logout,
whoami, connections, invoke and artifact get.
- Each app has its own device grant in the Keychain, chosen with --profile
or ZEOCORE_PROFILE. With no Keychain the command fails closed with exit 12.
- invoke derives its idempotency key from the request, so running the same
invocation again replays and never acts twice. It answers request_key and
retry. --wait-approval emits the approval link and replays the same key
until the person decides.
- KeychainSecureSessionStore(profile=...) keeps one entry per profile. No
profile keeps today's entry.
- The runtime-host names are a supported tier (planned for 0.15.0, after
0.14.0). zeo_core.adapters.runtime_host.canonical, .catalogue, .channel
and .host now declare __all__: canonical_bytes, digest, parse_json,
manifest_inventory, MAX_BYTES, ProtocolError, InvalidRequestError,
CandidateCatalogue, validate_inventory, RuntimeChannel, EffectPort,
ManagedHost, parse_result and prepare_request. Until this release they
were internal, with no stability promise. Nothing about them changes.
zeo_core.contracts.runtime.RUNTIME_HOST_PROTOCOL_VERSION (1) names the
version every versioned runtime-host-v1 model carries, so a consumer can bound
compatibility on it. The contracts/runtime-host-v1 schemas and vectors are
still not in the wheel; pin them by sha256 from the source tag.
The promise, from 0.15.0: while zeocore is 0.x, removing one of these
names or changing it incompatibly happens only in a minor release (0.y.0),
never in a patch, and is listed under "Breaking" in that release's entry.
From 1.0.0 it needs a major version. A wire-incompatible change to a
runtime-host-v1 model also raises RUNTIME_HOST_PROTOCOL_VERSION.
- The merger's decision core, ported into zeocore (zeo_core.merger). This
follows the operator's ruling that the merger is a zeocore app; ZEO-LEDGER owns
the decision contract and reviews the port.
- It's a port of zeomerger's register reader, decision core, pass and journal.
- It is held to ZEO-LEDGER's language-neutral parity fixtures, committed byte
for byte under contracts/merger-v1/: 29 decision cases (v2), 11 whole-run
cases (v4) and 14 register cases.
- It never writes the register, makes exactly one merge call per receipt with
sha set to the approved head, journals its intent durably before the call,
and reconciles a lost answer by reading.
- A merge call that provably never left the host (no token, or no
connection) is journaled not-sent. That releases the intent, so a later
pass decides again; anything that may have arrived stays unclear. The Go
oracle does the same (zeomerger 4eb8950, parity pass v4). An injected
HTTP client that follows redirects is refused, since a followed redirect
would make a later connect error no proof that nothing was sent.
- The base branch's required checks are read from its rulesets only, so a
branch under classic branch protection is refused (it fails closed).
- The GitHub adapter is in; the zeocore merger command follows.
- GitHub App installation tokens for an isolated principal
(zeo_core.integrations.github.app_tokens, github-app extra). These are
for the merger, which by the operator's ruling is a zeocore app whose key is
kept outside ZEOconnect.
- It signs an RS256 App JWT and mints a token for exactly one repository and
exactly the requested permissions. A broader grant is revoked and refused.
- It sends one attempt and never retries.
- The key is read only from the running user's own Keychain item, or from
FileAppKeySource: the user's own regular file with no group or other access,
never a symlink.
Changed¶
These change what a caller sees. The session store API and the
ZEOconnectHTTPTransport constructor (session_store, base_url,
allow_development_origin, http_client, clock) are unchanged.
| Broker answer | 0.13.0 | 0.14.0 |
|---|---|---|
403 {"code": "stopped", "control", "scope"} |
"hosted request was refused" | HostedStoppedError: "hosted request was stopped by <control> (<scope>)" |
| 503 with the protocol header | "hosted request was refused" | HostedUnavailableError: "hosted transport is unavailable" |
| 401 | "hosted request was refused" | one refresh, then the same request once more; a second 401 gives "paired device session was refused; pair this device again" |
| 426 | "hosted request was refused" | HostedUpgradeRequiredError, which says to upgrade zeocore |
| no connection to the production Broker | "hosted transport is unavailable" | HostedUnreachableError with the contract's off-network wording; a development origin keeps the old message |
| a response field zeocore doesn't know | the response is invalid | the field is ignored (contract §10) |
- A Broker 503 is an outage, never a refusal and never a stop (council
ruling E7). It is not evidence that an effectful request was not accepted,
and it grants no retry: an effect is sent once. The one safe read,
google.drive.file.download, is attempted a second time only when no response arrived, never because of a 503 (contract §9). -
"Refused" is not evidence of non-acceptance. Only a stop is a positive statement about what the Broker did.
-
PyPI
admitchecks what a non-Admin can see (the operator, SOW-29, option C). It no longer requires the exactv*ruleset bypass list, which GitHub hides from anyone without Admin, and no agent is an Admin under ruling r7. It requires the ruleset to be active onrefs/tags/v*with no exclusions, restricting creation, update and deletion, and matorclawson's owncurrent_user_can_bypassto benever(approver_can_bypassotherwise). A hidden bypass list is now read as hidden, not as an error. -
zero-employeeis no longer a PyPI target. It is now zeoruntime, released Go-only through the shared signed release component. -
make setupand CI install exactly whatuv.lockpins (make sync, which runsuv sync --lockedwith every gate extra plus dev, lint and docs). Before this,uv pip install -e .[extras]resolved the newest releases, so CI could test dependencies a release never ships (pydantic 2.14 against the locked 2.13.4 on super PR #100). A stale lock now fails setup instead of drifting. - One hosted error message is new. A Broker response with no
ZEOconnect-Protocol-Versionheader now raisesHostedClientError("hosted response did not come from the Broker"). Before, it raised "hosted protocol version is incompatible", which now means only a different or doubled header. No otherHostedClientErrormessage changes, and neither do the session store API or theZEOconnectHTTPTransportconstructor. Callers that match on the old message for a headerless response must match on the new one. - Breaking:
merge_pull_requestneeds the headshaand merges only bymerge.shais a required keyword, the full 40-hex commit the merge was approved for, and GitHub refuses the merge if the head has moved.squashandrebaseare refused. Nothing in zeocore called it. In ZEO, merging is zeomerger's alone (operator decision, 2026-10-10).
Deprecated¶
- The ZEOconnect client commands for seats (
zeocore login,logout,whoami,connections,invokeandartifact get). A seat useszeo, ZEO-RT's front door, for every Broker operation (ZEOCORE-SOW-27). The commands stay for a product running as its own macOS service user,zs-<product>(the first iszs-newsroom-intake). From Broker contract 1.4 the Broker refuses a product's grant from any other user,rodbotand an author's own login included, withapp_identity_unverified, and a seat's grant withdoor_required. The Broker enforces this, not zeocore.
Fixed¶
- Hosted access reaches ZEOconnect again.
ZEOCONNECT_PRODUCTION_ORIGINis nowhttps://broker.connect.zeo.ac, the Broker, which is reachable only on the organisation's private network (contract §2). The retiredhttps://connect.zeroemployee.organd the browser-facinghttps://connect.zeo.acare refused as transport origins (org #791). - YouTube retention no longer deletes data during a stop or an outage. A
Broker stop or a 503 used to read as "refused", which removed
youtube.jsonas if access had lapsed. Both now defer, as an unreachable Broker already did, until the 30-day limit. - A hosted request never carries NaN or ±Infinity. They are not JSON, and
the Broker refuses them (zeoconnect #49). httpx 0.27, which zeocore allows,
would have sent them. The transport now refuses such a body before sending,
with
HostedClientError("hosted request holds a number JSON cannot carry"). - A YouTube job survives a kill mid-write. The job directory's write-once
files (each event and
receipt.json) were created under their final name and then written. A process killed in between left an empty file, so the next run could not read the job at all. Each file is now written and synced under a temporary name, then hard-linked into place, which is still write-once. A filesystem without hard links is refused withJobErrorrather than written directly, because a direct write would bring back the partial file. This protects against a killed process. Power-loss durability also depends on the filesystem honouring fsync. - Unknown fields nested in a Broker response are ignored too. 0.14.0 drops
unknown top-level fields (contract §10), but an unknown field inside
artifactornormalized_errorstill refused the whole response. Both now drop unknown fields, so a later Broker can add fields at any level. Aprovider_detailis still refused. -
Two processes sharing a paired session no longer ask to re-pair. Refresh tokens are single use (contract §4). When a YouTube run and the retention sweep both hit a 401, both refreshed with the same token, and the loser reported "pair this device again" when nothing was wrong. zeocore now reads the session store again before refreshing, and again if the refresh is refused. A pair the other process rotated is used instead. One narrow window remains: if the refusal is read before the other process has saved its pair, the refusal stands.
-
A hidden ruleset bypass list is never read as empty. GitHub returns a ruleset's
bypass_actorsonly to a user with Admin on the repository.admitused to read the missing key as an empty list and refuse astag_ruleset_missing, naming the wrong cause. It now records the list as hidden, and doesn't rely on it (see Changed). -
The YouTube custody relay no longer retries a failure no retry can cure. Until now only a refusal ended a relayed upload: every other client error backed off and probed again, up to 20 times. That covered an incompatible protocol, an invalid answer, an expired or missing device session, and the managed-execution refusal. Now only "unavailable" and "pending" are transient. Anything else holds the job as
upload_rejectedafter one request. A refusal, a Broker stop included, still holds it assession_link_refused. - A Broker response without its protocol header is terminal everywhere.
On the relay, a 502/503/504 was read as an outage before the header was
checked. A proxy's headerless 503 was therefore retried as if the Broker had
sent it. Now the header is checked first on every Broker response, so a
missing, different or doubled header is a protocol failure. It is never
retried, refreshed around or read as a stop. A Broker 503 with the header is
still an outage and is retried (org #787, council ruling E5).
What this means in practice: a 502 or 503 from a CDN or edge proxy,
which carries no Broker header, is the most common real outage. It now ends
a relayed YouTube upload at once, holding the job as
upload_rejected, where before it was waited out. That is E5's choice. When the Broker is reachable again, append areleasedevent and the next run resumes the upload. - A GitHub effect is sent once, never retried.
make_requestretried every method on a 5xx, a rate limit, a timeout or a dropped connection. So one ambiguous reply could open a second pull request, post a second comment or issue, write a file twice, or merge twice. Only GET and HEAD are retried now. POST, PUT, PATCH and DELETE are sent exactly once, and an unknown outcome is raised for the caller to reconcile by reading back.
Known issues¶
- Hosted access stays unavailable in this release, as in every release since
0.10.0. The hosted origin is still pinned to
connect.zeroemployee.org, which no longer names the ZEOconnect deployment; local integrations are unaffected. This release changes relay failure handling. It does not claim conformance to Broker contract1.0.0and does not repair the hosted origin; both are for 0.14.0 (org #791).
0.12.0 - 2026-10-08¶
Added¶
- YouTube data retention (
youtube.retention,publish retain): YouTube's fields (the video id, privacy, schedule and link) live only in a replaceableyoutube.json, never in the write-once job files.retainrefreshes each record once it is 20 days old (onevideos.get, 1 unit). It deletes the record when the video is gone or access has lapsed, or when no refresh succeeded by day 29, and logs when and why. This follows the Developer Policies' 30-day limit (§III.E.4).Receiptno longer carriesprovider_object_id,video_urlorresponse_sha256; it points toprovider_record. - YouTube publishing for multi-GB files (
zeo_core.integrations.google.youtube): the provider client opens resumable sessions inside the custody boundary and never sends bytes;transfersends a file to a session link with no credential, probing first so a drop, kill or reboot resumes at the exact byte;jobandpublishare a write-once job directory (ZEO Runtime's occurrence identity, Go-computed test vectors) and an executor CLI (pair,connections,run,status) whose lost-final-answer path adopts one matching upload, holds on several, and never uploads twice. Replaces 0.11'supload_video. If YouTube refuses a link without a token, the job switches to a custody relay (relay.RelayByteHttp,ZEOconnectHTTPTransport.relay_youtube_chunk): sealed 4 MiB chunks through ZEOconnect, same session, same resume. Offline contract only; no live request has been made. - YouTube publishing (
zeo_core.integrations.google.youtube, extrayoutube): resumable chunked upload with progress, schedule (publish_at), metadata, thumbnail, caption track, playlist item, channel identity and video state. Injected credentials only (GoogleCredentialSource); it reads no credential file. Models refuse what YouTube would reject before any call. When YouTube keeps an upload private (an unverified API project), the result says so; a failed upload is never retried. Not in the setup catalogue. Offline contract only; no live request has been made. - Local Revolut Business enrollment (
zeo_core.integrations.revolut.local, extrarevolut): use your own account on your own machine, with no hosted service or database. Three explicit steps (setup,authorize,complete) as a CLI or in Python; key, certificate and rotating tokens in owner-only files outside any repository; configuration only from.env. One refresh per read; a marker is written durably before a refresh is sent, and a lost answer is a blocked unknown outcome that only a fresh consent clears. Registered as therevolut.businessentry point; the setup catalogue now reports the local profile as implemented. Offline contract only; no live request has been made. HostedServiceRegistry: explicit, immutable registrations replace the hosted resolver's hard-coded service branch. The reviewed default registers exactly the previously resolvablegoogle.drivedownload, so resolution is unchanged.- Read-only Revolut Business client (
zeo_core.integrations.revolut): accounts and one bounded, explicitly paged transaction page over a fixed origin, with exactDecimalamounts, declared normalization, byte bounds on the upstream body and the normalized result, observation timestamps and no credential path of its own. Offline contract only; no live provider request has been made. - Versioned, inert setup manifests for all twenty integration tracks, with current operation/capability mappings and explicit unadmitted hosted profiles.
- Seven-dimension availability snapshots that preserve every blocker, expiry and known revocation without conferring dispatch authority.
- Versioned resource-selection metadata distinguishing exact objects, fixed collections and explicitly dynamic future membership.
Fixed¶
- Local Revolut enrollment no longer clears an unresolved refresh when the
owner gives a fresh consent on the same registration. Consent authorizes new
tokens; it does not settle what the provider did with a request whose answer
was lost. The marker and its block survive: reads continue on the new access
token, refreshing stays blocked. A refused grant or a rejected token, which
are definite answers, are still cleared by a new grant. A new registration
records
follows_unresolved_refresh, and the guide no longer describes deleting a certificate as certain isolation: no qualified recovery exists. - A stored local Revolut enrollment is bound to its environment. Files written
for sandbox are refused by a production-selected object, and the reverse,
with
ENVIRONMENT_MISMATCHbefore any client is built or any credential is sent, including for completion and refresh. - Service requirements accept existing single-component service identities such
as
github, while retaining exact operation-prefix validation.
0.11.0 - 2026-09-10¶
Added¶
- Version-1 supervised Runtime capability host and
zeo-capabilityCLI with explicit provider binding, canonical schemas/vectors and private inherited IPC. Theruntime-hostextra is separate fromall. Joint Runtime/ZEOconnect wire agreement and real application acceptance remain required. - Runtime-admitted meeting-v1 adapters for Notion upsert, Sheets/Calendar reads and Gmail draft creation, retrieval and reconciliation, using their existing meeting request/receipt protocol.
- Offline catalogue and meeting-request examples, provider-registration guidance, and versioned installation guidance throughout the public docs.
- Searchable documentation with generated API reference and GitHub Pages publishing.
Fixed¶
- Legacy plugin registration publishes transactionally, restores surviving shadowed contributions on unload, uses registration snapshots for cleanup, and refuses ambiguous selected entry points before import.
- GitHub release announcements wait for published-package smoke checks, including the installed Runtime host extra, offline examples and missing-authority refusal.
0.10.0 - 2026-09-09¶
Added¶
- Governed Gemini reference-image commissioning with durable dispatch markers, private hashed artifacts, project-bound custody and read-only reconciliation. Image candidates remain unreviewed; ambiguous delivery never triggers another POST.
- Conversion receipts, versioned notebook semantic comparison and strict staged batches through the public Jupytext/Pandoc APIs. A complete reference consumer independently checks fixtures and runs in separate test/production roots.
- Optional
notebookextra for fresh-kernel execution with parent-enforced deadlines, bounded output, observed process cleanup, resolved interpreter and environment identity, declared lock provenance and explicit cell accounting. - Explicit test and production integration environments with a process launcher, scoped credential inputs, secure prompts and separate configuration, credential caches, temporary files and working directories. All sixteen integration entry points plus hosted ZEOconnect have detailed account and E2E setup guides.
-
Managed LLM runs fail on the selected provider instead of silently substituting another provider or mock; offline mock use requires explicit test fixtures.
-
Kit marketing integration and thirteen registered capabilities for broadcasts, sequence authoring, subscriber consent, tags and reporting. Includes explicit reviewed sends, safe error outcomes, an offline example and provider-contract tests.
-
HubSpot postmerge review corrections: tolerate inert null workflow decorations, allow reviewed unenrollment despite unrelated graph drift, and sanitize malformed provider schedule errors.
-
HubSpot marketing integration and eleven registered agent capabilities for newsletter drafts, reviewed publishing and scheduling, campaigns, subscription preferences and marketing email workflows. Includes bounded pagination, safe error outcomes, workflow ID mapping, an offline example and account-tier docs.
-
Native, consent-bound ZEOconnect composition with explicit
fake,local,hosted, and isolatedgovernedprofiles. Applications declare existing service/operation identities once and receive structured connection states without import-time or resolution-time networking. - An explicit device-pairing lifecycle, rotating device sessions, macOS Keychain custody, deterministic in-memory test custody, sanitized connection selection, and a fixed-origin/versioned ZEOconnect HTTP transport.
- A deterministic Drive fake and conformance proof that one Drive-read business function runs unchanged under fake, local, and hosted composition.
Fixed¶
-
Native fake and hosted service imports no longer require optional local Google or Bluesky dependencies; SDK loading is deferred until local service construction.
-
Notebook worker results are published atomically so polling parents cannot observe partially written JSON. Successful and failed publication paths have deterministic regression controls.
- Google Drive listing now uses the SDK's
pageSizekeyword in both listing paths. Real discovery-builder regression tests prevent permissive mocks from hiding a broken first account check. - Bind full HubSpot workflow reads to the requested ID before graph review or follow-up enrollment, update, activation, metrics and archive requests.
- Kit mutation responses now require a valid operation-bound resource ID; a newsletter send must return a new ID distinct from its source draft. Invalid identities retain an unknown outcome without retrying.
- HubSpot unenrollment rejects metadata for missing, malformed or mismatched workflow IDs before mapping or deletion, while permitting unrelated graph drift.
Changed¶
httpxis now a base dependency because the hosted bridge is part of normal ZeoCore installations. Construction remains inert and ignores ambient proxy configuration.- New hosted invocation requests omit connector revisions. ZEOconnect derives the immutable revision from the authenticated connection; the 0.9 request field remains optional for source compatibility during server migration.
Security¶
- Managed Supabase launches reject identical test and production project URLs, even with distinct keys, before creating state or starting the application.
- Managed integration children disable ambient netrc lookup, preventing HTTP clients from replacing a selected token with credentials from the user home.
- Hosted resolution and Supabase remain separate boundaries: the ZeoCore client accepts no Supabase URL, key, database role, Vault reference, tenant ID, or provider credential.
- Governed resolution cannot instantiate a hosted client, load a paired-device session, or fall back to member authority. Effects never receive the safe-read transport retry granted to the first Drive observation.
0.9.0 - 2026-09-06¶
Added¶
- First-class Supabase integration through the maintained
supabase>=2.31,<3Python SDK. Thezeocore[supabase]extra exposes runtime-checkable, injectable services for bounded PostgREST CRUD and named RPC, secret-free Auth dispositions, bounded Storage, named Edge Functions, and explicit async Realtime subscriptions. - Typed filters, ordering, row pages, user/session status, bucket metadata, Function results, and Realtime changes. Update/delete require filters; identifiers, object paths, response sizes, caller headers, and project URLs fail closed.
Security¶
- Supabase keys remain owned by the auth/client-construction seam and are absent from configuration and public results. Privileged server keys require explicit opt-in and never imply application authorization.
- Raw SQL, arbitrary URLs, signed bearer URLs, the Management API, and
vault.decrypted_secretsare deliberately absent. Provider exception text is discarded before it can carry credentials into logs or receipts. - Supabase OAuth start rejects an authorization URL outside the configured project origin. Lazy Realtime construction keeps its project key opaque and releases the local reference after SDK construction.
Fixed¶
- Supabase convenience methods now return a structured uninitialized result instead of raising while resolving the absent client.
Documentation¶
- The Supabase tutorial now walks from project creation and publishable-key selection through Row Level Security, first read, Auth, Storage, Functions, Realtime, privileged-key isolation, and production verification.
- The Notion tutorial now teaches the admitted
notion.page.upsertcontract, deterministic marker, cited content, dispatch/reconciliation boundary, and hosted versus local custody paths. A credential-free runnable example makes the request and connector revision inspectable without issuing an effect.
0.8.0 - 2026-09-05¶
Added¶
- A complete adapter-neutral
BrokerExecutionStoreprotocol now covers the durable nonce, idempotency, evidence, and outcome surface used byEffectOrchestrator. SQLite remains the local implementation; hosted stores no longer need to import or impersonate it. ObservationOrchestratorprovides a separate durable path for admitted READ operations: exact authorization and selected-resource binding, atomic idempotency, bounded and sanitized inline/artifact results, immutable receipts, and failed-safe timeout handling without mutation-style ambiguity.- The admitted
notion.page.upsertoperation includes a closed request shape, deterministic marker, one-call dispatcher, read-only reconciler, and Keychain custody path. A lost create response reconciles by marker without a second create. - Hosted Notion OAuth credential dispatch accepts organization-bound
SecretRefobjects for refresh, introspection, and revocation while keeping raw token material inside the custody callback. - Google Drive and Docs accept injected credential sources and client
factories. The named selected-file scope profile uses only
drive.file. - A credential-free ZEOconnect client boundary and local/hosted service factory provide protocol-compatible Drive download, Docs read, and confirmed Bluesky post services. Remote downloads are size/digest verified and local paths never cross the network.
Changed¶
- Notion SDK construction has an explicit proxy policy and disables accidental ambient proxy inheritance by default. Unit tests inject provider fakes; a separately selected profile may opt into ambient transport configuration.
- Workspace connector extras now include the legible
docs,sheets, andslidesaliases in addition to the sharedgooglefamily extra. - Coverage is measured to two decimals and guarded by a boundary meta-test: 89.99 fails and 90.00 passes.
Fixed¶
- Release gates can no longer print success after accepting a rounded below-threshold coverage result.
- The HTTP callback test now matches the real synchronous boundary and no longer leaves an un-awaited mock coroutine.
- Jupytext fixtures carry stable cell IDs instead of relying on nbformat's temporary repair behavior.
- README test-suite wording and Bluesky tutorial release evidence no longer describe stale 0.6-era bytes.
0.7.0 - 2026-09-05¶
Added¶
- Complete Notion API
2026-03-11integration through the officialnotion-client>=3.1.0SDK: 44 current data operations spanning pages, blocks, databases, data sources and templates, users, search, comments, custom emoji, file uploads, views, meeting notes, and Markdown. Pagination, request-size limits, bounded retry metadata, and currentin_trashand block-position semantics are explicit. Public OAuth covers authorization-code exchange, refresh, introspection, and revocation while placing issued bearer credentials directly intoSecretStorecustody. - Durable effect orchestration under
zeo_core.connections: an organization-scoped SQLite store, exact fail-closed authorization verifier with required signature verification and issuer/audience trust configuration, persisted pre-dispatch state, one-call provider dispatch, fail-closed ambiguity, reconciliation without blind redispatch, atomic outcome receipts, and sanitized confirmation evidence. Connector admission closes origin, path, redirect, request-field, secret-binding, and reconciliation surfaces;KeychainEffectDispatcherconfines credential material to a one-shot custody callback. - Bounded read/advisory retries and explicit provider fallback under
zeo_core.execution, including hard subprocess deadlines, process-group cleanup, cancellation, and one-attempt LLM adapters.
Changed¶
- Notion credentials now enter through environment variables or OAuth custody; normal configuration and public results no longer carry raw bearer material. Historical convenience methods remain available, but removed request fields fail closed and ambiguous multi-data-source database calls must name the data source explicitly.
- PyPI project URLs, release instructions, public repository links, and package
examples now point directly to
zeroemployeeorg/zeocoreafter the repository move. - Published authentication results no longer carry raw provider tokens. Credential-bearing constructor input is rejected rather than merely hidden by selected serializers.
Fixed¶
- The publish workflow now creates the matching GitHub release only after PyPI succeeds, and its clean-environment smoke test installs the exact version that the workflow built instead of permitting resolver fallback to an older one.
- The stable required
verify-allcontext now fails visibly when any Python matrix leg fails, avoiding a permanently pending required check after matrix changes.
0.6.0 - 2026-08-31¶
Two new integrations and the credential handling to support them safely. Short announcement: RELEASE_NOTES.md. Adopter path: install -> GET-STARTED.md token guide -> construct an integration -> post.
Added¶
- Google Docs integration (
zeo_core.integrations.google.docs): fulldocuments.v1surface --get_document,create_document,batch_update, plusget_document_textwith a recursive body walk that includes tables. Index-freereplace_text/append_textare the headline editing methods; the request builder reverse-sorts by index internally so earlier edits cannot invalidate later ones. - Bluesky integration (
zeo_core.integrations.social.bluesky), the first provider under a newintegrations/social/package. Authenticates with an app password -- no OAuth, no developer app, no approval. Rich-text facets are computed from UTF-8 byte offsets, so links and mentions survive emoji. - Google Sheets integration (
zeo_core.integrations.google.sheets): reading and writing cell ranges over the Sheets v4 API, sameIntegrationResultshape as every other integration. - Google Slides integration (
zeo_core.integrations.google.slides): presentation and page access over the Slides v1 API. - Tutorials for the integrations, under docs/tutorials/ and indexed from docs/README.md -- Google Docs and Bluesky join Calendar, Notion, MCP, capability authoring, results-and-errors, and context/config/files. Every code block in the two new ones was executed against the installed package before being written, not transcribed from source.
make doctor-- a readiness check that reports what an environment is missing rather than failing opaquely.make release-check-- pre-tag gate over version identity, the Python floor across every file that states it, the CHANGELOG entry, and index availability on both real PyPI and TestPyPI, each probe carrying a positive control so an unreachable index cannot read as a free filename.- Token-acquisition guide in GET-STARTED.md for Bluesky, LinkedIn, Google, Notion and GitHub: which portal, which product, which scopes, and where the value goes. Flows that could not be verified are marked as unverified rather than guessed.
.envis now actually loaded (zeo_core.config.load_dotenv_file). It was documented as the home for secrets but inert.
Changed¶
-
Python floor raised to 3.14 (was 3.13). This is a breaking change: an environment on 3.13 will no longer resolve new releases. It aligns zeocore with sovereign-agent 1.1.0, which already requires 3.14. Verified before landing -- the full suite passes on 3.14 with the same 2954 tests and no behavioural difference, and mypy is clean across 295 source files at the new floor.
-
Credential files move out of the working directory to an OS-appropriate per-user location via
platformdirs. A legacy credential is migrated once, with an explicit notice; differing contents in both locations refuses and instructs rather than guessing. Credential writes are0600and atomic. - OAuth credentials are now validated against granted scopes, not requested ones. A cached token missing a scope previously reported valid and failed at the first API call.
Fixed¶
driveandcalendarresolved configuration in__init__, so constructing either from a directory with no config file raised before a caller could supply one. Both now defer toinitialize(), matchingmail. All five integrations construct from a fresh directory.google_credentials.jsonandgoogle_client_secret.jsonwere not gitignored while the settings YAML was -- the settings file was protected and the live token was not.
0.5.0 - 2026-08-23¶
ZeoCore is the canonical capability-authoring and capability-contract
library for the Zero Employee ecosystem. Sovereign Agent is not moved
into this package. Short announcement: RELEASE_NOTES.md.
Adopter path: install → examples/capability_authoring.py
→ GET-STARTED Capabilities → HTTP/MCP examples.
Added¶
- Canonical capability contracts:
CapabilityId(namespace.name@semver),CapabilityDefinition,CapabilityManifest,CapabilityEffects/ConcurrencyMode/EffectKind,CapabilityRequirements, typedRequestGuard/GuardResult,CapabilityInvocationRecord(digests + redaction, not execution receipts), andCapabilityOutcomelayered on the existing three-wayCapabilityStatus. Seesrc/zeo_core/contracts/README.md. @capabilityfunction authoring,CapabilityRegistry(includingzeo_core.capabilitiesentry points),invoke_sync/invoke_async,tool_to_capability, andregister_capability_operationfor HTTP/MCP.- OpenAI function-tool projection in
zeo_core.adapters.llm_tools(project_openai_tool): refuses unsupported JSON Schema instead of silently weakening it. - Representative catalog capabilities under
zeo_core.tools.catalog(local add, filesystem checksum, GitHub file read, calendar create, pandoc markdown-to-docx). Reference implementations, not a public API. - Sovereign consumption contract pack (
zeo_core.contract_pack, tests undertests/contract_pack/) with nosovereign_agentimport. - Runnable examples:
capability_authoring.py,capability_guards.py,tool_to_capability.py,llm_tools_usage.py, rewrittenhttp_adapter_usage.py. Tutorial:docs/tutorials/capability-authoring.md. - Symbol audit and replacement-readiness reports under
docs/reports/(maintainer/ecosystem, not end-user docs).
Changed¶
- Package version aligned at
0.5.0(pyproject.tomlandzeo_core.__version__). Contracts module version is1.1.0. - Ecosystem Python ruling recorded: forthcoming Zero Employee releases align on Python 3.13; ZeoCore does not restore 3.12 CI.
- README / GET-STARTED /
llms.txtlead with@capabilityas the canonical authoring surface.BaseZeoToolremains fully supported.
Compatibility¶
- Existing
BaseZeoTool.run(), HTTP, and MCPregister_toolpaths remain. CapabilityResult.ok/.skip/.failset default outcomes so current tools need no changes..unavailable()is the skip path for missing declared services.- Effects are declarations, not authorization. Human approval is not a capability result state.
Named, not fixed¶
zeo_core.tools.compat.sovereign_style_capabilityexists for keyword-argument functions migrating from Sovereign Agent style. It is transitional, not canonical. No deletion timeline in this release.- LLM provider
chat()still does not parsetool_useresponse blocks into structuredtool_calls(request-side tool-calling works). Same gap as 0.4.x;adapters.llm_toolsprojects ZeoCore capabilities outward and does not close that inbound parse gap.
0.4.0 - 2026-08-21¶
Changed¶
.envadopted as the documented home for secrets (RULING-356). Not a runtime change — zeocore already mergesos.environover YAML config, so this changes where a byte is typed, not what the process does with it. It is adopted because YAML config files get committed by default and.envfiles do not, and this library's stated audience is junior: defaults are the whole product for that audience. A new.env.exampleships at the repo root with placeholder values forNOTION_TOKEN,GITHUB_TOKEN,OPENAI_API_KEY, andANTHROPIC_API_KEY..envis not loaded on import — that stays the caller's shell/tooling, a deliberate fence (see "Named, not fixed" below).GET-STARTED.mdfixed — the highest-severity item in this release. The documented "Creating Custom Configuration" walkthrough was teaching a junior to construct a secret inline (MyAppConfig(api_key="your-api-key")) and then.model_dump()it into aZeoConfig.customdict that gets persisted to a committed YAML file. A second, previously-uncited instance in the same file's "Configuration File Format" section embedded a literalapi_key: "your-api-key"in a worked YAML example. Both rewritten to read the secret from the environment and keep it out of anything persisted to disk.README.mdwas swept for the same shape; no instance found there..gitignorenow anchors the two repo-relative default config locations (/zeo_config.yaml,/config/zeo_config.yaml, perconfig/loader.py:52-57). Defense in depth: a junior who ignores the docs and types a secret into config YAML is now stopped by a rule rather than their own attention. Verified withgit check-ignore -v/git add --dry-run, not by reading the pattern.
Fixed¶
- Credential files are now written
0600. Amode: int | None = Noneparameter threads through the fs write chain (write_json/write_yaml/write_bytes/write_text, both the atomic and non-atomic branches); default is preserve-current, so general-purpose infra (pandoc/jupytext/gmail output, etc.) is unchanged. The three credential writers (google/auth.py,notion/auth.py,github/auth.py) now passmode=0o600explicitly. The real defect:_atomic_writepreserved a pre-existing loose file mode forever, with no path to tighten it, on every subsequent write. New files were already born0600under this repo's own umask probe — this is not a create-at-0644fix; that defect does not exist.
Named, not fixed (recorded per circle-of-control)¶
- The env-writeback opt-in (
zeo_core.integrations.llms.config. LLMConfigProvider._setup_environment_variables,llms/config.py:228-273) copies anapi_keyfound in loaded YAML config intoos.environwhen the corresponding env var isn't already set. Real, and ranked, but sized this round rather than changed: only one gated production call site reaches it (prompt/_internal/enhancer.py:27, itself behind an explicituse_llmopt-in at its only caller,prompt/service.py:161); the other construction site,llms/__init__.py:73'screate_integration(), is dead code —modules/discovery.pylooks only forcreate_pluginand states so in its own comment.get_llm_client(llms/registry.py:41), the function GET-STARTED.md's own worked example actually uses, does not go through this path at all. Default-OFF for this behaviour is still a breaking change; this release only narrows the estimate from an[INFERRED]broad surface to one enumerated, already-gated site. - Typed secret models (
SecretStr) cannot be applied as-is.ZeoConfig(models.py:100-138) has no secret-shaped field to type —integrationsandcustomare both untypeddict[str, Any], and secrets flow through them structurally the same as any other config value. AdoptingSecretStris a design decision about how to shape that dict, not a drop-in annotation change, and stays open. - Two of the four default config locations are outside any repo-local
.gitignore's reach.config/loader.py:52-57also names~/.zeo/config.yamland/etc/zeo/config.yaml; a secret typed into either is not covered by this release's.gitignorepatterns or by any mechanism in this repo, because neither path is inside a git working tree..envremains the documented, gitignore-independent mitigation regardless of which config location is in use.
0.3.0 - 2026-08-20¶
Added¶
- Google Calendar integration (
zeo_core.integrations.google.calendar,zeocore[calendar]extra): read (list_calendars,get_calendar,list_eventswith date-range filtering,get_event) and write (create_event,update_event,delete_event) surface, reusing the same OAuth (InstalledAppFlow+ local-server) flow andGoogleAuthProvider/GoogleConfigProviderthe Drive and Gmail integrations already use — no new auth or config mechanism. Seeexamples/calendar_usage.pyanddocs/tutorials/calendar-integration.md. zeo_core.integrations.googlenow also re-exportsGoogleCalendarService,Calendar, andCalendarEventat the shallow path (alongside the existingGoogleDriveService/GoogleMailServicere-exports).
Named, not fixed (recorded per circle-of-control)¶
zeo_core.integrations.google.drive.operations/*(list_files.py,upload.py,download.py,folder.py,permissions.py) is dead code: confirmed by a repo-wide grep that nothing outside drive's own test suite imports it —drive/service.py's public methods duplicate the same logic inline rather than calling intooperations/. Pre-existing, not introduced by the Calendar integration (which does not replicate this pattern), and out of this work's own scope to fix.GoogleDriveService/GoogleCalendarService's realintegration_idproperty ("googledrive"/"googlecalendar", derived fromname.lower().replace(" ", ".")) does not match the dottedpyproject.tomlentry-point table key ("google.drive"/"google.calendar") — the two are different strings by a pre-existing pattern (confirmed identical forGoogleDriveService), not a defect introduced by the Calendar integration.
0.2.0 - 2026-08-20¶
BREAKING¶
- Python floor raised from
>=3.10to>=3.13. Python 3.10 is inside its own final support window (security-only since October 2023, full end-of-life October 2026); 3.13 is also the version theffmpegextra (below) needed to resolve at all (ffmpeg-zeorequires Python >=3.12). If you're pinned to an older interpreter, stay on a pre-0.2.0release of this package; otherwise upgrade before installing. CI's version matrix was trimmed from["3.10", "3.11", "3.12", "3.13"]to["3.13"]to match — the dropped legs could not pass regardless of this change (3.10/3.11 failffmpeg-zeo's own floor; keeping them past the bump would test versions the package no longer claims to support).
Added¶
- MCP server adapter (
zeo_core.adapters.mcp,zeocore[mcp]extra): expose zeocore tools to Claude Code, Cursor, and other MCP-native coding agents. AnyBaseZeoToolbecomes MCP-callable with zero MCP-specific code from the tool author —register_tool()mechanically derives the MCP tool definition from the tool's ownrun(request, ctx)type hint and registers it into the sameOperationRegistryzeo_core.adapters.httpalready reads, so one registration reaches both adapters. Seeexamples/mcp_server_usage.pyand GET-STARTED.md's "Exposing Tools as an MCP Server" section. - Notion integration (
zeo_core.integrations.notion,zeocore[notion]extra): full read (get_page,list_page_blocks,search,get_database,query_database) and write (create_page,create_database_entry,update_page,append_blocks) surface, bearer-integration-token auth (Notion's own model, not OAuth). Handles thenotion-clientSDK's 2025-09-03 database→data-source model change transparently — callers still pass adatabase_id. Seeexamples/notion_usage.py. - Jupytext integration (
zeo_core.integrations.jupytext,zeocore[jupytext]extra):script_to_notebook()(percent-format.py→.ipynb, matching howquackslidesuses jupytext today) andnotebook_to_script()(its natural inverse). Seeexamples/jupytext_usage.py. - FFmpeg integration (
zeo_core.integrations.ffmpeg,zeocore[ffmpeg]extra): wraps the org's ownffmpeg-zeoPyPI package (not the rawffmpegbinary directly).probe(),convert(),transcode_h264(),extract_audio(),thumbnail(). Seeexamples/ffmpeg_usage.py. LLMOptions.cache_system_prompt: marks the system prompt cacheable via Anthropic'scache_control: ephemeralbreakpoints. Provider-agnostic field on the sharedLLMProviderProtocol; a no-op on providers without caching support (OpenAI, Ollama).llms.txt: a condensed package summary for coding agents / LLM context windows.
Fixed¶
- Anthropic client's default model updated (both
clients/anthropic.pyandconfig.py'sAnthropicConfig.default_model) — the previous default,claude-3-opus-20240229, was retired 2026-01-05. - Real Anthropic-shaped tool-use request passthrough:
LLMOptions.toolsis converted to Anthropic's flat{name, description, input_schema}shape and reaches the real request. Known gap, not yet closed: response-side tool-call extraction is incomplete —chat()only readsresponse.content[0].text, so atool_useresponse block is not parsed into structured output today. See GET-STARTED.md's LLM providers section for the full detail. zeo_core.integrations.googlenow re-exportsGoogleDriveServiceandGoogleMailServiceat the shallow path (previously only reachable at.google.drive/.google.mail).CapabilityResultre-exported from the top-levelzeo_corepackage (previously only reachable viazeo_core.contracts).- GET-STARTED.md's configuration quick-start corrected (an unmarked
placeholder path was being presented as a runnable example); a real,
runnable
examples/config_usage.pyadded. Makefile'sinstall-alltarget was missing themcp/mcp-devextras, silently skipping the MCP adapter's own dependencies on a plainmake install-all— fixed.- An order-dependent test failure
(
test_configure_logger_attaches_real_file_handler, passed in isolation, failed under full-suite ordering) was root-caused to afunctools.lru_cache-backed filesystem-service singleton leaking a stale working directory across tests, and fixed by scopingcache_clear()around the affected test.
Research (no code shipped)¶
- Database integration (BigQuery, Supabase, SQLite) was evaluated and
not built this round: BigQuery dropped (zero consumers anywhere in
the org); Supabase held (its only real consumer,
profrod-site, is TypeScript and architecturally unreachable from this Python package); SQLite judged buildable but not urgent (quackresearchalready self-serves with hand-rolledsqlite3). Thezeo_core.integrations.databasepackage directories exist as empty stubs — not yet implemented.
Changed¶
CapabilityResult.machine_messageandCapabilityError.codenow acceptZEO_<AREA>_<DETAIL>(new preferred prefix, matching thezeo_corepackage name) andZC_<AREA>_<DETAIL>(short-form alias), in addition to the legacyQC_<AREA>_<DETAIL>inherited from the pre-extractionquack_corepackage. Previously onlyQC_was accepted, which contradicted this file's own 0.1.0 "full mechanical rename" claim below (see that entry's amendment) and had no documented reason for surviving the rename. This is a backward-compatible widening, not a breaking change: all 0.1.0 code usingQC_*codes continues to validate unchanged. All of this package's own internal call sites (tools/mixins/env_init.py,contracts/capabilities/demo/_impl.py,examples/toolkit_usage.py,contracts/EXAMPLES.md) were migrated toZEO_*to lead by example.
0.1.0 - 2026-08-17¶
Initial extraction from the quackverse monorepo as a standalone, MIT-licensed package.
Added¶
zeo_core.tools: a capability-authoring framework (BaseZeoTool,ToolContext,ZeoToolProtocol) with optional mixins (IntegrationEnabledMixin,LifecycleMixin,ToolEnvInitializerMixin) for writing doctrine-compliant tools.zeo_core.contracts: typed data contracts (CapabilityResult, artifact and manifest models, common enums and IDs).zeo_core.core: filesystem operations (core.fs), path resolution (core.paths), a typed error hierarchy (core.errors), MIME detection, serialization helpers, logging, and an operation registry.zeo_core.config: YAML/environment-variable configuration loading and per-tool configuration models.zeo_core.integrations: adapters for GitHub, Google Drive, Gmail, LLM providers (OpenAI, Anthropic), Notion, and Pandoc.zeo_core.modules: plugin discovery and explicit-loading registry.zeo_core.prompt: prompt template selection and enhancement utilities.zeo_core.adapters: an optional FastAPI-based HTTP adapter for exposing tools over a REST API.examples/: runnable, verified example scripts (toolkit_usage.py,minimal_tool.py,error_handling.py).CONTRIBUTING.md,CODE_OF_CONDUCT.md(Contributor Covenant v2.1).
Changed¶
- Full mechanical rename from the monorepo's
quack_corepackage tozeo_core(PyPI distribution name:zeocore), including class names (Quack*->Zeo*), environment variable prefixes, and config file keys. Amendment (see Unreleased): this rename did not originally extend to theQC_*machine-message/error-code prefix enforced byCapabilityResult/CapabilityError's validators, which kept rejecting anything butQC_-- contradicting "full" above. Fixed by widening those validators to also acceptZEO_/ZC_, rather than retroactively editing this historical entry. - Fixed a broken version-sourcing path and a production test-detection bug found during the extraction (see git history for detail).
Fixed¶
- CI now runs the full test suite on every supported Python version (3.10-3.13) on real GitHub Actions infrastructure. That surfaced three real, previously-invisible cross-version bugs (this package's own pre-release local development only ever ran on 3.13), all fixed and independently verified across every supported version before release:
- A
pathlib.Path.__init__/__new__split changed in CPython 3.12; an autouse test fixture that monkeypatchedPath.__init__only was crashing the entire test suite on 3.10/3.11 with anINTERNALERROR. Fixed by coercing on both__new__and__init__, matching whichever one actually does the real work on a given Python version. unittest.mock's dotted-string@patch(...)target resolution changed in 3.11 (pkgutil.resolve_nameinstead of an eagergetattr-walk). Three call sites depended on the newer resolution semantics to reach their intended target; on 3.10 they silently patched the wrong object, cascading into shared-state pollution across unrelated test files.typing.Protocol.__instancecheck__'s structural-membership check changed in 3.12 (from plainhasattrtoinspect.getattr_static, which does not triggerMagicMock's attribute auto-fabrication). Five tests asserting that a bare, unconfiguredMagicMock()does not satisfy a runtime-checkable protocol passed on 3.12/3.13 but failed on 3.10/3.11. Fixed by constructing the mocks with an explicitspec=, which is version-stable and expresses the real test intent.
Removed¶
- The
BaseZeoToolPluginback-compat alias -- unused outside this repo's own test suite, and this package has never had a public release, so no back-compat was owed for it.