Repository navigation
Releases
librarian v0.23.2
From running librarian on kagent with kagent's default model, and from asking what someone needs to see before putting it into the stack they already run.
A real run, on a build of what is released here. The full minute.
Fixed
- An agent that found its operation in a search made the body's field up. Among several APIs,
capabilitiessaid of an operation only that it takes a body, and a small model went straight on to the write with a field of its own (comment, where the API takestext): on kagent, 2 of 6 writes had the right body.write,write_planand the A2Awriteandplanskills now say where a body's fields are told, andcapabilitiesnames a body's first fields among several APIs too, wherever the whole answer has room for them: always for a few small APIs, and among large ones as before. 12 of 12. - An agent whose write was waiting ended its turn instead of waiting. Told only that
write_statuscan wait, it asked its user whether it should, about one run in five on kagent with the skill and eight in ten with only the tools. The answer to a write that waits now says the next step in so many words: callwrite_statuswithwait_seconds45, once, before answering. 12 of 12.
New
examples/kagent: ten minutes. librarian from the chart beside kagent on Agent Substrate, a demo API, and one Agent with librarian's tools and skill. An agent that holds no credentials reads, then asks for a change that you approve on a page. Run from an empty kind cluster on Kubernetes 1.37, as kagent's guide asks, and on 1.35 with its feature gates.examples/agentgateway: five minutes. librarian behind agentgateway with Docker: agents use the gateway's address for MCP and A2A, people use librarian's pages. It is the configuration the docs give and the weekly run tests, and a test keeps it so.- The docs show it running. A recording of the kagent example, light and dark, at the top of the README, in the guides and on the site. Nothing in it is re-enacted; pauses while the model thinks are cut, and the pages say so.
- For each stack: what you add, what to run, how it is tested. One table in the README, In the stack you already run, for any MCP client, any A2A client, LiteLLM, agentgateway, and kagent with Agent Substrate.
- How kagent support is tested, said plainly. What runs with every commit, what was run by hand, when and on which versions, and what has never been run on a cluster (integrations).
- The README's links work on PyPI. The package's page is the README, where forty links to files of the repository led nowhere. The release points them at GitHub, at the release's tag.
Upgrade
- No configuration changes are needed.
capabilitieswithoutapimay name what bodies hold."body": ["text", "seen?"]where it said"body": true, when the whole answer has room for it. The answer stays undercapabilities_max_bytes. On GitHub's API alone, a search answer for an agent that may write grows from 6.5 to 7.7 KB; answers without a query, and answers for agents that only read, are unchanged.- An agent told that its write waits is now told to wait once, for 45 seconds or
mcp_max_wait_secondsif that is less. Withmcp_max_wait_seconds: 0it is told to ask again later, as before. - The skill's text changed in two places. A kagent Agent takes it from this release's image by digest:
oci: ghcr.io/kultar/librarian@sha256:84a51695c96c34aad2dec16e092a02cd3dcefc5c31589b814fe148df0a596c1d,path: skills/librarian. An older one keeps working.
Checked on kagent 1.0.1 (Agent Substrate 1.0.0, Kubernetes 1.37.0) with its default model, through agentgateway v1.7.0, and by the five integration stacks. Not run on a cluster: Agent Substrate without kagent, and any managed Kubernetes.
librarian v0.23.1
Two things from live runs against what 0.23.0 tells agents about request bodies.
Fixed
- A list field is named by its key, and its type says that it is a list. 0.23.0 named a list field of a body
expand[](the notation of a registry entry). A model asked to make a Stripe refund sent just that as the key:{"expand[]": ["charge"]}.capabilitiesnow answers{"name": "expand", "type": "list of string"}, and a field of each item of a list asitems.priceunderitems, alist of object. With that, a small and a large Claude model both sent{"expand": ["charge"]}, and a small one built a GitHub tree of two files as a list of objects at the first attempt. Upgrade if agents use 0.23.0's body fields.
New
- A body is sent as a form where the API takes one. An agent gives a body as an object, whatever the API takes. APIs such as Stripe's take a form (
application/x-www-form-urlencoded) and refuse JSON, so a write that was read, approved and sent as JSON failed there. librarian now sends it the way the API's description says: a field inside another in brackets (metadata[order]=6735), a list of objects numbered (items[0][price]=p1), and a list of plain values as that description writes lists: the name repeated (tag=a&tag=b, OpenAPI's default), numbered in brackets (expand[0]=charge, where the description gives the styledeepObject, as Stripe's does), or joined by commas (Swagger 2). - The approval page shows the fields as they go over the wire, under the body, for such a write.
- A body that cannot be a form (a list, for an operation that takes a form) is refused in words before anyone is asked to approve it.
capabilitieswithapiandoperationsays"sent_as": "form"for such an operation. For one whose description wants a file upload (multipart) it says that librarian does not send that; 0.23.0 said"sent_as": "multipart", which was not true.- In an entry:
body.lists(repeated,bracketsorcommas) besidebody.encoding(the format). - The skill tells agents to give
bodyas an object and not to write names likemetadata[order]themselves. A kagent Agent takes it from this release's image by digest:oci: ghcr.io/kultar/librarian@sha256:159bb5ccaeb8fddfe11d3e24b9ee399cfd5046c46e1b127f34b6563f4355ffc5,path: skills/librarian.
Checked with a real HTTP client against a real server (the bytes on the wire), through agentgateway against an echo server in the weekly stack, and on Stripe's own description: 306 of its operations are read as forms with bracketed lists. Not checked against Stripe itself.
Upgrade
- No configuration changes are needed.
- An API learned by 0.23.0 knows that it takes a form, and not how its lists are written. Have its description read again: Re-check now on the console's API page, or
librarian registry recheck <api>. For an approved API an approver then takes the update, which touches nothing else. An API learned before 0.23.0 gets both at the same step. - An entry with
lists: bracketsorlists: commascannot be read by 0.23.0, which reports it invalid and goes on serving the others. That concerns APIs that take forms; an entry without it is written as before. - A change in how a body is taken, at the source, is listed like any other change in a body, and holds no operation back.
librarian v0.23.0
An agent that was told only that an operation takes a body had to guess what goes in it. In live runs a small and a large Claude model both said so, and answered from what they knew of the API: that works for Stripe, and gives nothing to go on for an internal API. librarian now reads what a request body holds from the API's description, and tells it.
For every agent
capabilitieswithapiandoperationgives that operation in full: every argument with its type and description, and every field of its body with its type, whether it is needed, the values it takes and what it is for.labels[]is a list,author.namea field inside another. Up to 40 fields, three levels deep.capabilitieswithapinames the first fields of each body:"body": ["head", "base", "title?", "draft?"], withbody_morewhen there are more than ten. Among several APIs an operation still saysbody: true, to keep that answer small.- The skill (
skills/librarian) tells agents to ask before a write instead of guessing. A kagent Agent takes it from this release's image by digest:oci: ghcr.io/kultar/librarian@sha256:f27f8114f3f7d61ea763903a1acf256599bf3f0c03e1ff575979899e36f1ad82,path: skills/librarian.
In a live run with only the tools, a small model asked to open a draft pull request asked about the operation first and sent {"head": "fix/typo", "base": "main", "title": "...", "draft": true} at the first attempt. Asked what a Stripe refund takes, a small and a large model both listed the twelve fields with their types and values from librarian's answer.
For the people who run it
- The console's API page shows what a body holds, under each operation.
- Read from OpenAPI and Swagger descriptions (
requestBody,in: body,formData), through$ref,allOf,oneOfandanyOf. Not from documentation pages or from a model's knowledge. A body can be written into an entry by hand (the format). - Told, not enforced. Nothing is checked against it: the API accepts or refuses a body. A change in a body at the source is listed as a change and holds no operation back.
- APIs learned before get their bodies when their description next changes, or at once when a person asks: Re-check now on the console's API page, or
librarian registry recheck <api>, which now read a description again even where it has not changed. For an approved API that is an update an approver takes. It adds the bodies and touches nothing else that was decided about the operations. The daily look at the sources does not do this by itself, so nobody gets a card they did not ask for.
Measured on GitHub, Stripe, Jira, PagerDuty and DigitalOcean: 1,343 of the 1,497 operations that take a body are described. A body has two to six fields at the median. An entry grows by a quarter (GitHub: 1.26 MB to 1.59 MB) to double (Stripe).
Upgrade
- No configuration changes are needed.
- An entry that has body fields cannot be read by 0.22 or earlier. Every API learned or read again by 0.23 has them. After a rollback, such an API is reported as invalid and is not served until you roll forward again; nothing is lost. For the same reason, finish the rollout before agents learn APIs.
capabilitieswithapiand no query lists fewer operations of a large API (30 of each kind for GitHub, where it was 50), because each one now names what its body holds. The note in the answer says how to see the rest.- Finish the rollout before agents use
operation: a replica still on 0.22 does not know the argument. - librarian still sends a body as JSON. Where an API's description says it takes a form (Stripe's does, for every operation), the answer says
"sent_as": "form"; such an API may refuse the write.
librarian v0.22.2
capabilities is the first thing an agent asks, and all of its answer goes into the agent's context. With a few large APIs that answer had grown to tens of thousands of tokens: agent clients warn about a tool result of that size, put it aside in a file, or refuse it. This release keeps it to a size an agent can take, however many APIs there are.
For every agent
- The answer of
capabilitieshas a size it stays under:capabilities_max_bytes, 16,000 bytes of JSON (over MCP up to about 28,000 characters of text, some 9,000 tokens for a Claude model). When it would be larger, the lists of operations are cut to the same length for every API, and anotein the answer says what was left out and how to see it. Every API is still there with how many operations it has. capabilitiestakesapi: that API alone, and with aqueryits operations that fit. This is what the note points to.- With a query, the API that fits it best keeps its matches; the lists of the others are cut. An agent that names the API it wants gets that one as before.
- Past a few dozen APIs not all of them fit even without their operations: the first ones are listed and
more_apishas the ids of the others. - An API named another way is answered with the one that exists:
unknown API 'GitHub'. Did you mean 'github'?, incapabilities,execute,writeandwrite_plan, and only among the APIs that agent may use (or, for a write, may write to). - The skill (
skills/librarian) says whatapi,noteandmore_apisare for. A kagent Agent takes it from this release's image by digest:oci: ghcr.io/kultar/librarian@sha256:9a71c96003f280c495b9cfd15cefb459b947fedc148df67b7e5d33ecdb3c91c3,path: skills/librarian. An Agent that keeps an older digest keeps working: the answers themselves say what to do.
Measured on five large APIs (GitHub, Stripe, Jira, PagerDuty and DigitalOcean: 3,911 operations) for an agent that may ask for writes and gives no query: the answer was 120,000 characters of text over MCP (39,000 tokens) and is 26,000 (8,500), with ten reads and ten writes for each API. Claude models given only the tools followed the note to the operation they were asked for.
Upgrade
- This changes a default. An answer of
capabilitiesabove 16,000 bytes of JSON used to be sent whole and now has its lists cut.capabilities_max_bytes: 0gives the old behaviour (over MCP, the lists are still cut to whatmcp_max_result_bytesholds). An answer under the limit is what it was. - No configuration changes are needed.
- Finish the rollout before agents use
api: a replica still on 0.22.1 does not know the argument. - A gateway in front that lists tool arguments has one more to pass on:
capabilitiestakesapi.
librarian v0.22.1
A patch release from the first real agent that was given librarian's skill and a plain task ("add this comment to record 42"). It was shown the operations without their arguments, so it guessed: two operation names and one argument name were refused before a request went through. With 0.22.1 the same task takes one request, the right one.
For every agent
capabilitiesnames what each operation takes. Every operation comes withargs, the names of its arguments (team?is one that may be left out), andbody: truewhere it takes one.- A refusal over arguments says what the operation takes:
unknown arguments for 'addComment': record. It takes: id and a body. - An operation written another way is answered with the one that exists:
unknown operation 'add_comment' on 'demo'. Did you mean 'addComment'?Only among the operations that agent is shown anyway: nothing is suggested thatcapabilitieswould not list for it. - A search whose words fit an API but none of its operations lists them all the same.
capabilitieswith a query used to return such an API with an empty list, and the agent started guessing. It now gets the first 20. - The skill (
skills/librarian) tells agents to use the names inargs. A kagent Agent takes it from this release's image by digest:oci: ghcr.io/kultar/librarian@sha256:fd43776773c3a5e8d226e314d57d63e67c1734523e2f92c0062489f7de98dbc6,path: skills/librarian.
Documentation
- README, Big APIs: what
capabilitieslists (the ten best-fitting APIs and 20 operations of each to a query, the first 50 of each API without one) and how large its answer is.
Upgrade
- No configuration changes are needed.
capabilitiesanswers are larger, about 1.3 to 1.8 times. Measured on GitHub's API: 3 KB to a query for an agent that only reads, 7 KB for one that may also ask for writes.- Three refusals say more than before (unknown arguments, a missing required argument, an unknown operation). Whatever matched their whole text has to match their beginning.
librarian v0.22.0
Behind agentgateway
- Tested behind agentgateway v1.7.0, as an MCP server and as an A2A agent, with nothing changed in librarian. Two arrangements: each agent's own key passes through, or the gateway signs people in and passes their token on, which librarian verifies itself, so it knows the person with proof and not on the gateway's word. The stack runs in the weekly integration workflow.
- On Kubernetes the chart attaches librarian to your Gateway:
agentgateway.enabledandagentgateway.gateway.namecreate anHTTPRouteand twoAgentgatewayBackends (MCP at/mcp, A2A on every other path). Run on kind with agentgateway v1.7.0 and Gateway API v1.6.3. The sign-in arrangement is tested standalone, not as anAgentgatewayPolicyon Kubernetes. - Configuration and what to know behind it.
On kagent
- An agent can wait for a person. Nothing can wake a kagent session when an approval arrives.
write_statusnow takeswait_seconds: it answers as soon as the write or plan has ended, or after that time with where it stands (at mostmcp_max_wait_seconds, 50). The answer to a write that waits says so itself. It works across replicas: the agent can wait on one while another makes the write. - Tested on kagent 1.0.1, on its default harness and its Claude-based one: a plan of two writes approved once and waited for in one tool call, an agent given only some of the tools, and kagent's own approval (
requireApproval) in front of librarian's. - What kagent says about the person, shown as what it is. kagent can send the signed-in user's name in a header that nothing signs, set in the sandbox where the agent itself runs commands. With
substrate.claimed_user_header: X-User-Id(chart:substrate.kagent.claimedUserHeader) the approval page, the Slack card and the audit trail say: "The agent's platform names kim@example.com: nothing signs that, and it does not make them the requester." It is never the requester and never reaches an API that acts as the person. Off by default. - A skill for agents.
skills/librarianis an Agent Skill that tells an agent how to read through librarian, how to ask for a change and wait for the person, and what each answer means. It is also in the image, at/skills/librarian, which is where a kagent Agent takes it from, by digest:oci: ghcr.io/kultar/librarian@sha256:a8ad876192a6e4da9ac89a852ef4265238c462c5fe32ef81a3d82788885c18f8(this release),path: skills/librarian. Run on kagent 1.0.1: given only "add the comment … to record 42", an agent with the skill found the operation, asked for the write with a reason, waited for the approval and finished in the same turn. (kagent 1.0.1 could not take it from git: the sandbox in which an Agent is prepared could not resolve the git host.)
For every agent
- An answer too large to send comes back as its outline. Over MCP a tool result carries an answer twice (structured and as text). Past about 1 MB as sent, MCP clients and gateways refuse it and say only that a message could not be sent.
executenow answerstoo_largewith the fields of the answer and how many items its lists have, and the agent asks again withselect. The limit ismcp_max_result_bytes(1,000,000;0turns it off). This changes a default: answers above about 480 KB of data used to be sent whole. capabilitiesnames the operations that write. It listed reads only, so an agent could not find out which operation makes a change. Where an agent may ask for writes on an API it now also getswrite_operations, held to its limits like the reads, each with whether anybody has enabled writes through it.- In the MCP Registry as
io.github.kultar/librarian, with the PyPI package (uvx librarian-a2a serve;librarian-a2ais now a second name for the command) and the image.
Fixed
- Nothing an agent or an API wrote is read as markup by Slack. An agent's reason, its arguments, the name of an API it onboarded and an API's error text went into the cards as they were;
<!channel>would have pinged a channel, and<https://...|Approve here>would have been a link with those words. Every text is now escaped where it leaves for Slack, and only librarian's own mentions and links are markup. - Stopping could hang. librarian closed its database while writes asked for without waiting were still being waited for; on SQLite the process could then fail to exit. It now ends those tasks first. (They are picked up again at the next start, as before.)
- Onboarding with no database and a registry folder that cannot be written to failed with "Error executing tool onboard". It now says that there is nowhere to keep what was learned, and which settings change that.
Documentation
- The README names every command, every setting with its default, every tool and skill and every kind of authentication; the chart's README describes every value. Tests fail when one is missing, stale or shown with a wrong default.
- New: a README section on gateways and agent platforms, guides for agentgateway and kagent, troubleshooting for both, and what the threat model says about gateways, Slack text and unsigned claims.
Upgrade
- No configuration changes are needed.
- If an agent reads answers of more than about 480 KB of data over MCP, it now gets
too_largeand has to ask for less withselect. To keep the old behaviour setmcp_max_result_bytes: 0, and raise the limits of what is in between (agentgateway:frontendPolicies.http.maxBufferSize). - If a gateway or an MCP client in front of librarian has a request timeout under 50 seconds, set
mcp_max_wait_secondsbelow it, or agents that wait for a decision fail there first. - Finish the rollout before agents use
wait_seconds: a replica still on 0.21 does not know the argument. - Agents that may ask for writes now see the names and summaries of the operations that write on those APIs.
librarian v0.21.0
Several writes as one plan
- One decision for a change that takes several requests. A commit through GitHub's API is a blob, a tree, a commit and a branch, and then a pull request. Asked for one at a time, each needed its own approval and the approver saw each without the others. A plan (
planover A2A,write_planover MCP) puts them in front of the approver together, each request shown where it will go and with its body, and is approved once. The writes are then made in order. - A later step can use what an earlier one returned:
{"sha": {"$from": "blob.sha"}}, in an argument or anywhere in a body. The approval page marks what is not known yet. - Checked twice. Every step passes the policy check of a write before anyone is asked, and again just before it is sent, with the values now filled in and against the registry as it is then. An argument an agent's limits restrict, and anything a DELETE is sent, has to be written in the plan itself.
- It stops where it fails, and says so. The first step that fails or cannot be checked ends the plan; nothing is undone. The outcome names the step and what was made before it, and every step has a state: made, failed, not sent, or unknown when a request went out and no answer came back.
- A plan is on one API, holds only writes and at most 20 of them, never runs under a grant or automatic approval, and counts against the write rate limit as as many writes as it has steps (so
writes.rate_limit_per_minute, 10 by default, is also the longest plan an agent can ask for). More.
Limits inside an API
apisandwrite_apissay which APIs an agent may use.limits, on a caller or on an Agent Substrate rule, says what it may do inside one: which operations, and which values their arguments may take (owner: [acme],repo: ["payments-*"]).- An operation that takes none of the limited arguments cannot be held to anything, so it is refused unless
allow_withoutnames it; a limited argument the API treats as optional must be given. - Decided by the policy engine for reads, writes and the planner's calls. A call outside the limits is refused, not put to an approver, and no grant reaches past them.
capabilitiesshows an agent only what it can reach. Only arguments are looked at, not what a request body names. More.
Credentials made for each call
Three kinds of authentication where nothing long-lived goes to the API, and often nothing is stored at all:
- OAuth 2.0 client credentials: the API gets a token that expires by itself; the client secret goes to the token endpoint only.
- A GitHub App instead of a personal token: a token for each call, valid for an hour, limited to the repository the call names, and read-only when the call is a read.
- AWS Signature Version 4: every request is signed, as librarian's own identity or as a role assumed for that API for 15 minutes. There is no key to store.
They can be used on approved entries only. An API's authentication can now be described in full on its page in the console, and a credential that was made and then refused is reported as that, not as a missing key. More.
Whatever an API does
- The agent is told what happened. When an API cannot be reached or does not finish answering, the agent is told so in those words, with the reason when there is one (the name did not resolve, the connection was refused, its certificate was not accepted, it did not answer in time), instead of "internal error". For a write it is also told whether the request can have reached the API: "was not sent" or "may have reached it".
- One request has a time limit as a whole (twice
request_timeout_seconds), however slowly an answer trickles in. - An answer is passed on as data only if everything after librarian can handle it: JSON nested deeper than 100 levels arrives as text,
NaNandInfinityasnull. - A write always ends. An approval can no longer stay "executing" after a failure or a stopped replica: it is closed with what is known (after 15 minutes, or ten times the request timeout if that is longer) and never sent again by librarian. A repeat with the same idempotency key is refused while the first is still open.
librarian doctorlooks through the database and the audit file for credentials that versions before 0.20 could have stored there and names them by their reference;--redactreplaces the copies in the database.- The audit record of a write names the approval it was made under, and for a plan the step.
- These are tested as a whole: a fake API with every misbehaviour we know of (40 of them) runs through the service, A2A and MCP, as a read, as a write and as the middle step of a plan.
Upgrade
- No configuration changes are needed.
limitsand the new kinds of authentication are there when you use them. - Finish the rollout before using what is new. A replica still on 0.20 cannot read an entry that uses one of the new kinds of authentication, and does not know plans.
- If you ran a version before 0.20, run
librarian doctoronce: it finds any credential those versions stored outside the secret store. Replace the credentials it names at the API, then run it with--redact. - If a gateway in front of librarian lists the tools agents may call, add
write_planthere for the agents that should have it. - What an agent is told when an API does not answer has changed from "Internal error in the librarian" to a sentence naming the API and the reason; a task still ends as failed.
librarian v0.20.0
The database decides; GitHub is the record
- Approvals take effect at once. Approving a learned API, enabling writes and every other decision is now a database write, in effect on every replica immediately. There is no pull request to merge and no registry sync to wait for.
- GitHub receives a commit for every decision and is never asked. Each approved entry and decision is written to the record repository afterwards, in the background and with retries; a failed or slow GitHub never blocks or undoes a decision, and the repository is not read back.
librarian registry restorerebuilds a database from it. - Updates to a verified API get their own page. When an API changes at its source, approvers get an approve-or-deny page for the update. Any API can be approved or forgotten from the console.
- The chart no longer needs git-sync for the record (
githubApp.repo).
Agents on Agent Substrate and kagent
- Agents call librarian with no key of their own. Their sandboxes hold no credentials: the platform's egress gateway signs each request with the actor's identity, librarian verifies it against the cluster's issuer, resolves the session to its kagent Agent, and applies the rule for that agent (
substrate.rules: which APIs, which writes, who approves). Grants, rate limits and the audit trail follow the agent across its sessions. - The chart registers librarian with kagent as a
RemoteMCPServer(substrate.enabled), under its fully qualified name, and mounts the cluster signer's trust bundle. - Tested end to end on kind (Kubernetes 1.35) with kagent 1.0.1 and Agent Substrate 1.0.0; the steps and manifests are in
tests/integration/substrate. Through kagent the person behind an agent is not known, so a rule's owner approves that agent's writes.
Security fixes
- An API that sends the key back no longer hands it to the agent. Some APIs answer with the request they received: an echo or debugging endpoint, a link that repeats the query string with its key, an error page that quotes the URL, a message that names the rejected key. librarian passed such an answer on, to the calling agent, to the model planning a plain-language request, and into the result stored with a write's approval. The credential a call was sent with is now removed from every answer first (shown as
[redacted]): as sent, for Basic authentication also as the encoded pair and its password, and as a URL, a JSON string or an HTML page would write it. A value shorter than six characters is left alone, because replacing it would mangle ordinary data. - A stored key that ends with a line break no longer leaks through an error. A key created from a file usually ends with a line break. With such a key in the environment or AWS Secrets Manager store, the HTTP client refused the request with an error that quotes the header it refused. On 0.19.1 that put the read key into librarian's log and, for an approved write, the write key into the agent's answer and the approval's record. Now whitespace around a stored credential is not sent (so such a key simply works), a key with a line break or a non-ASCII character inside it is refused before anything is sent, with a reason that does not name it, and the HTTP client's own message is never passed on.
- Dependencies:
certifi2026.10.23 (the older CA bundle trusts roots whose intermediate keys were compromised; this is the bundle behind librarian's outbound calls),pyasn10.6.5 andopentelemetry-api1.45.2 (denial-of-service fixes).
After upgrading: results and failure notes stored by earlier versions are not rewritten. If you write to an API that sends its key back, or a write ever failed with "Illegal header value", replace that write key. Logs from earlier versions may hold a read key in the same error.
Upgrade
- From 0.19 or earlier with a registry repository: upgrade with your values unchanged, so the first start imports the reviewed entries into the database. Check the console lists your APIs, then set
githubApp.repoand dropregistry.gitSync. Review pull requests librarian left open are closed with a comment saying where the review continues. Details: docs/registry.md. - Answers may now contain
[redacted]where an API repeated the credential. Nothing else in an answer changes. - No other configuration changes.
substrate.*is off unless you enable it.
librarian v0.19.1
Fixes from a real write flow (blob, tree, commit, ref, pull request)
- Idempotency keys work everywhere. A repeat with the same
idempotency_keywas matched in one pod's memory only, so with two replicas a retry on the other pod sent the write again and opened a second approval; grant and automatic writes were never matched at all. The key is now indexed with the write in the database: a repeat returns the earlier result on any replica and after a restart, and a repeat while the first is still pending joins that approval instead of opening another. Failed, denied or expired writes do not block the key. - The agent is told how a write ran. Every executed write now carries a
message: approved by whom; under which grant (who created it, until when); approved automatically (n of cap today); or not sent again because this key already ran. Grant and automatic writes get an approval id too, sowrite_statusfinds them. write_statusdates the result.result_as_ofand a message say the result is the API's response when the write ran and the resource may have changed since.- A decision is stored before waiters see it. A waiter polling at the wrong moment could try to claim a write the database still showed as pending and be told it was "already being run".
- GitHub SAML enforcement. A 403 "Resource protected by organization SAML enforcement" is explained in the write's error (authorize the token with Configure SSO), and the credential page for GitHub hosts says so up front.
- Rate limiting is not a permission problem. A 429, or a 403 with
X-RateLimit-Remaining: 0, aRetry-Afterheader or a rate-limit message, was reported as "the credential is valid but lacks permission", sending people to check scopes and SSO. It is now reported as rate limiting, with the reset time (fromRetry-AfterorX-RateLimit-Reset) and "retry then", in the error and in the audit record. On any 4xx or 5xx the audit record keeps a short, redacted excerpt of the API's own message (upstream), and the error quotes it. - Quieter grants. A grant covering a multi-step flow posted one channel card per step.
writes.announce_grants: false(chart:config.writes.announce_grants) stops the post for every grant, and the console's Grants page now has a Notices control to turn it off per grant (notify_owner, which until now only config-file grants could set). On by default. Every use stays in the audit log, the server log and the Activity page.
Upgrade
No configuration changes.
v0.19.0
Grants last as long as the approver chooses
"Approve and allow similar writes" used to offer 1, 7 or 30 days, and the backend quietly capped a grant at 90. Approvers now choose: 1, 7, 30 or 90 days, a number of days of their own, or until revoked.
- Adjust later. The console's Grants page gets a Set control on every active grant: a new expiry counted from now, or until revoked. Shorten, extend or revoke at any time; each change is audited (
grant_adjusted). Grants from the config file are changed in the file, as before. - Ceiling.
writes.max_grant_days(chart:config.writes.max_grant_days) caps how long a grant may last; the pages then offer only lengths within it and refuse the rest. Unset by default, so until revoked is allowed. - Unchanged. DELETE operations are never granted or automatic, use caps and pinned arguments work as before, and the approval page says who may approve as of 0.18.2.
Upgrade
No configuration changes. Set writes.max_grant_days if your policy wants every grant to expire.
