read_library #
Generated automatically from the published contract sources.
A script calls this action over HTTPS at POST https://turnzero.ai/api/v1/actions/read_library, with a bearer credential and the action's payload as the JSON body. It also accepts GET. An MCP connection lists this action as the tool tzcloud_read_library.
Build metadata: Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.
Contract description #
List the published code library, or read one entry by entry. Any signed-in connection can call this. With no entry, each row gives a name, version, content hash, and selection summary. The full list can be large: narrow it with contains, or pass installed with held_only: true. With entry, read its file list, or pass file for that file's content. Continue a chunked file with next_offset as offset and its stamp until the offset is null; decode base64 where indicated and check the joined content against sha256. history: true lists earlier versions and dates, not their files.
To take the entry, run download.command_npx (download.command_npx_windows on Windows) at your project's root, then follow download.next.
More about this action #
Pass contains to get only the entries whose name or summary contains that text, ignoring case. An entry listed in installed is always returned. Where no entry matches and held_only is not true, the result's note lists every served entry by name.
The installed argument: The result then gives every entry a standing. The standing is current, newer, or withdrawn for an entry this list includes, and not_held for a served entry the list leaves out, which is compared with nothing. With held_only, only the entries in this list are returned. Two calls return fewer not_held rows: one passing held_only: true returns none, and one passing contains returns only those its text matches.
Read one published library entry: its file list with a hash and size per file, or, with file, one file's content. A package's import name is the name in its served package.json, which resolves to lib/index.js, the re-export of the package's runtime modules. Its testing subpath has the test double, which only an application's tests import. With no token for library take, a signed-in tool reads each listed file here, the double's lib/testing.js among them. A large file reads in chunks: pass limit, then each result's next_offset as offset with its stamp until it is null. Check the joined content, decoded when encoding is base64, against sha256. To take the entry, run the result's download.command_npx, or download.command_npx_windows on Windows, at your project's root, then do what download.next says.
It takes no version: it reads the version read_library lists, since each publication replaces the library whole.
The file list has a package's compiled runtime modules under lib/, never its source or tests. Any signed-in connection can read it.
Inside a package's copy, the entry's package.json is beside its lib/ folder, kept as a folder, as Use the library's step 5 shows; npm install links the copy into node_modules, which you never write.
With entry and history: true, the result also lists that entry's previously published versions, with the times each was published and superseded. An inventory read carries no version history. No call reads an earlier version's files: previous_versions gives each one's number and dates, never its files.
Access and action metadata #
{
"name": "read_library",
"resource": "library",
"tier": "observe",
"surface": "tzcloud",
"access": "anonymous",
"summary": "The library's inventory: catalog rows and their selection summaries, served to any connected identity, and on the wire to a request carrying a credential of an account. With `entry` it reads one entry: One published entry: its file list with a hash and a size per file, or one named file's content, whole or, with `offset`, `limit`, and `stamp`, in chunks on the served context's paging, the stamp the file's hash and a stale one refused context_changed. It is served to any connected identity, and on the wire to a request carrying a credential of an account, like the inventory beside it. A tool reads a package's test double, `lib/testing.js`, here with no token for the take line. Latest only: a publish replaces what is served, and a consumer keeps its own copy of what it holds.",
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"openWorldHint": false,
"idempotentHint": true
}
}
MCP catalog entry #
{
"name": "read_library",
"title": "Read feature library",
"tier": "observe",
"scenario": "API-L0-15",
"summary": "List the published code library, or read one entry by `entry`. Any signed-in connection can call this. With no `entry`, each row gives a name, version, content hash, and selection summary. The full list can be large: narrow it with `contains`, or pass `installed` with `held_only: true`. With `entry`, read its file list, or pass `file` for that file's content. Continue a chunked file with `next_offset` as `offset` and its `stamp` until the offset is null; decode base64 where indicated and check the joined content against `sha256`. `history: true` lists earlier versions and dates, not their files.\n\nTo take the entry, run `download.command_npx` (`download.command_npx_windows` on Windows) at your project's root, then follow `download.next`.",
"owners": [
"API-L0-15",
"LC-06",
"LC-02",
"LC-05",
"CTX-07"
]
}
request #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Additional properties: false Replaced members: name was replaced by entry |
| / |
The published entry to read, by the name this call lists. Leave it out to list the library. The read takes no version: it reads the version this call lists.Type: string |
| / |
One file's path within the entry, to read its content; omit it for the file list. Type: string |
| / |
With file: a zero-based Unicode code-point offset in the file's content as the answer encodes it; defaults to 0. Pass the previous chunk's next_offset to continue. A nonzero offset requires its stamp.Type: integer Minimum: 0 Maximum: 9007199254740991 |
| / |
With file: the most Unicode code points of content this chunk returns, 1 through 16000, default 8000. Pass offset, limit, or stamp to read the file in chunks; pass none and you read it whole.Type: integer Minimum: 1 Maximum: 16000 |
| / |
With file: the stamp the previous chunk returned, which is the file's SHA-256. Required with a nonzero offset. A publish that changed the file returns context_changed; restart at offset 0 without a stamp.Type: string Pattern: ^[a-f0-9]{64}$ |
| / |
Pass true to get the entry's previous_versions: each earlier version's number and the times it was published and superseded. Leave it out or pass false and you get none. Over the HTTP route a value other than true or false is refused invalid_request.Type: boolean |
| / |
The entries your project already holds, each {name, version, hash} from its manifest row, hash being the row's closure_hash. The answer then marks each entry current, newer, or withdrawn, and marks not_held a served entry this list does not include.Type: array |
| / |
Type: object Required fields: ["name","hash"] Additional properties: false |
| / |
Type: string |
| / |
The version held, as the manifest row records it. Type: ["string","null"] |
| / |
The vendored copy's recorded closure hash, compared with the served closure hash. Type: string |
| / |
With installed: true returns only the entries in that list, each marked current, newer, or withdrawn and each row whole, and leaves out every not_held row. True without installed is refused invalid_request. Defaults to false.Type: boolean |
| / |
Only the entries whose name or summary contains this text, ignoring case, and every entry in installed, which is returned whatever the text. An empty or absent contains narrows nothing.Type: string Maximum length: 200 |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version"] Additional properties: false |
| / |
Required value: 1 |
| / |
Type: array |
| / |
Type: object Required fields: ["name","kind","closure_hash"] Additional properties: false |
| / |
Type: string |
| / |
Type: string |
| / |
Type: ["string","null"] |
| / |
Type: string |
| / |
Type: ["string","null"] |
| / |
Type: array |
| / |
Type: string |
| / |
Present when your request passed installed. Standing current: the held hash equals the served closure hash. Standing newer: it differs. Standing withdrawn: the held name is no longer served, the row returned from your own item. Standing not_held: the served entry is not in your list and was compared with nothing, and no such row is returned where your request passed held_only.Allowed values: ["current","newer","withdrawn","not_held"] |
| / |
Type: object Required fields: ["name","files"] Additional properties: false |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Type: ["string","null"] |
| / |
Type: string |
| / |
Type: ["string","null"] |
| / |
Type: array |
| / |
Type: string |
| / |
Type: string |
| / |
Under history: true alone: each previously published version of this entry with the times it was published and superseded, oldest first. The list does not carry them. A versionless entry gains none. Each gives an earlier version's number and dates, never its files: no call reads an earlier version's files.Type: array |
| / |
Type: object Required fields: ["version","published_at","superseded_at"] Additional properties: false |
| / |
Type: ["string","null"] |
| / |
Type: string |
| / |
Type: ["string","null"] |
| / |
Type: array |
| / |
Type: object Required fields: ["path","sha256","size"] Additional properties: false |
| / |
Type: string |
| / |
Type: string |
| / |
Type: integer |
| / |
Type: object Required fields: ["path","encoding","content","sha256"] Additional properties: false |
| / |
Type: string |
| / |
Allowed values: ["utf8","base64"] |
| / |
Type: string |
| / |
Type: string |
| / |
On a chunked read: the stamp to pass with the next chunk, the file's SHA-256. Type: string Pattern: ^[a-f0-9]{64}$ |
| / |
On a chunked read: this chunk's code-point offset in the file's content. Type: integer Minimum: 0 Maximum: 9007199254740991 |
| / |
On a chunked read: the content's length in code points. Type: integer Minimum: 0 Maximum: 9007199254740991 |
| / |
On a chunked read: the next chunk's offset, null at the last chunk. Join the chunks' content in order, decode it where the encoding is base64, and check its SHA-256 against the file's. Type: ["integer","null"] Minimum: 0 Maximum: 9007199254740991 |
| / |
With the entry answer, on the MCP surface alone. command is the one line that takes the entry with the turnzero command's library take, on the origin of the platform that responded. command_windows is the same line for Windows. Run at the project's root, the line checks every listed file against its SHA-256 and the entry's closure hash before it writes anything. It then writes the entry's row in the library folder's manifest.json and replaces the entry's folder there whole. For an entry with compiled modules, it copies package.json and lib/ into the application's folder and runs npm install. Its next says where to run the line and which form to run, and hands what remains to the line it prints starting next:, which lists for that folder the files to commit and what the application manifest needs. An entry whose name the line cannot carry gets next alone, saying so.Type: object Required fields: ["next"] Additional properties: false |
| / |
One line, for macOS and Linux: turnzero library take --entry <name>, then --origin <origin> off https://turnzero.ai. Run it once, as given, at the project's root. It ends 0 where the entry was taken, 1 where its install failed, and 3 where nothing was written.Type: string |
| / |
Present with command: the same line for every Windows shell, with turnzero.cmd where its head says turnzero. On Windows, run this one in command's place, as given.Type: string |
| / |
The same line run through npx, npx --no-update-notifier -y turnzero@<tag> in place of turnzero, the tag latest on production's platform and next on every other. It is present exactly where command is. Run this line first, or command_npx_windows on Windows; it runs whether or not the command is installed. If your safety check refuses it, run command where turnzero --version responds, else deploy_files for a deploy or install the command. A person or a job may run any of the four forms.Type: string |
| / |
command_npx's line for every Windows shell, with npx.cmd where its head says npx.Type: string |
| / |
Type: string |
| / |
The library commit this publish was read at. A project's folder manifest must record, per entry, the commit it was published from; the fact lives on the catalog rather than on any row, so it is returned here or it is unreachable. Absent before the first publish. Type: string |
| / |
When this publish ran, ISO 8601. Distinct from an entry's own published_at, which is when that entry last changed. Absent before the first publish. Type: string |
| / |
Present where contains matched no served entry's name or summary and held_only was not true: one line listing every served entry by name, so a word the library does not use still shows what it serves.Type: string |
Complete payload contract #
{
"request": {
"type": "object",
"additionalProperties": false,
"x-renamed": {
"name": "entry"
},
"properties": {
"entry": {
"type": "string",
"description": "The published entry to read, by the name this call lists. Leave it out to list the library. The read takes no `version`: it reads the version this call lists."
},
"file": {
"type": "string",
"description": "One file's path within the entry, to read its content; omit it for the file list."
},
"offset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "With `file`: a zero-based Unicode code-point offset in the file's content as the answer encodes it; defaults to 0. Pass the previous chunk's next_offset to continue. A nonzero offset requires its stamp."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 16000,
"description": "With `file`: the most Unicode code points of content this chunk returns, 1 through 16000, default 8000. Pass offset, limit, or stamp to read the file in chunks; pass none and you read it whole."
},
"stamp": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "With `file`: the stamp the previous chunk returned, which is the file's SHA-256. Required with a nonzero offset. A publish that changed the file returns context_changed; restart at offset 0 without a stamp."
},
"history": {
"type": "boolean",
"description": "Pass `true` to get the entry's `previous_versions`: each earlier version's number and the times it was published and superseded. Leave it out or pass `false` and you get none. Over the HTTP route a value other than true or false is refused `invalid_request`."
},
"installed": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"hash"
],
"properties": {
"name": {
"type": "string"
},
"version": {
"type": [
"string",
"null"
],
"description": "The version held, as the manifest row records it."
},
"hash": {
"type": "string",
"description": "The vendored copy's recorded closure hash, compared with the served closure hash."
}
},
"additionalProperties": false
},
"description": "The entries your project already holds, each `{name, version, hash}` from its manifest row, `hash` being the row's `closure_hash`. The answer then marks each entry `current`, `newer`, or `withdrawn`, and marks `not_held` a served entry this list does not include."
},
"held_only": {
"type": "boolean",
"description": "With `installed`: true returns only the entries in that list, each marked `current`, `newer`, or `withdrawn` and each row whole, and leaves out every `not_held` row. True without `installed` is refused `invalid_request`. Defaults to false."
},
"contains": {
"type": "string",
"maxLength": 200,
"description": "Only the entries whose name or summary contains this text, ignoring case, and every entry in `installed`, which is returned whatever the text. An empty or absent `contains` narrows nothing."
}
}
},
"response": {
"type": "object",
"required": [
"contract_version"
],
"additionalProperties": false,
"properties": {
"contract_version": {
"const": 1
},
"entries": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"kind",
"closure_hash"
],
"properties": {
"name": {
"type": "string"
},
"kind": {
"type": "string"
},
"version": {
"type": [
"string",
"null"
]
},
"closure_hash": {
"type": "string"
},
"summary": {
"type": [
"string",
"null"
]
},
"supersedes": {
"type": "array",
"items": {
"type": "string"
}
},
"standing": {
"enum": [
"current",
"newer",
"withdrawn",
"not_held"
],
"description": "Present when your request passed `installed`. Standing `current`: the held hash equals the served closure hash. Standing `newer`: it differs. Standing `withdrawn`: the held name is no longer served, the row returned from your own item. Standing `not_held`: the served entry is not in your list and was compared with nothing, and no such row is returned where your request passed `held_only` (LC-06)."
}
},
"additionalProperties": false
}
},
"entry": {
"type": "object",
"required": [
"name",
"files"
],
"properties": {
"name": {
"type": "string"
},
"kind": {
"type": "string"
},
"path": {
"type": "string"
},
"version": {
"type": [
"string",
"null"
]
},
"closure_hash": {
"type": "string"
},
"summary": {
"type": [
"string",
"null"
]
},
"supersedes": {
"type": "array",
"items": {
"type": "string"
}
},
"published_at": {
"type": "string"
},
"previous_versions": {
"type": "array",
"items": {
"type": "object",
"required": [
"version",
"published_at",
"superseded_at"
],
"properties": {
"version": {
"type": [
"string",
"null"
]
},
"published_at": {
"type": "string"
},
"superseded_at": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"description": "Under `history: true` alone: each previously published version of this entry with the times it was published and superseded, oldest first. The list does not carry them. A versionless entry gains none. Each gives an earlier version's number and dates, never its files: no call reads an earlier version's files."
},
"files": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"sha256",
"size"
],
"properties": {
"path": {
"type": "string"
},
"sha256": {
"type": "string"
},
"size": {
"type": "integer"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"file": {
"type": "object",
"required": [
"path",
"encoding",
"content",
"sha256"
],
"properties": {
"path": {
"type": "string"
},
"encoding": {
"enum": [
"utf8",
"base64"
]
},
"content": {
"type": "string"
},
"sha256": {
"type": "string"
},
"stamp": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "On a chunked read: the stamp to pass with the next chunk, the file's SHA-256."
},
"offset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "On a chunked read: this chunk's code-point offset in the file's content."
},
"total": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "On a chunked read: the content's length in code points."
},
"next_offset": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 9007199254740991,
"description": "On a chunked read: the next chunk's offset, null at the last chunk. Join the chunks' content in order, decode it where the encoding is base64, and check its SHA-256 against the file's."
}
},
"additionalProperties": false
},
"download": {
"type": "object",
"description": "With the entry answer, on the MCP surface alone. `command` is the one line that takes the entry with the turnzero command's `library take`, on the origin of the platform that responded. `command_windows` is the same line for Windows. Run at the project's root, the line checks every listed file against its SHA-256 and the entry's closure hash before it writes anything. It then writes the entry's row in the library folder's `manifest.json` and replaces the entry's folder there whole. For an entry with compiled modules, it copies `package.json` and `lib/` into the application's folder and runs `npm install`. Its `next` says where to run the line and which form to run, and hands what remains to the line it prints starting `next:`, which lists for that folder the files to commit and what the application manifest needs. An entry whose name the line cannot carry gets `next` alone, saying so.",
"required": [
"next"
],
"properties": {
"command": {
"type": "string",
"description": "One line, for macOS and Linux: `turnzero library take --entry <name>`, then `--origin <origin>` off `https://turnzero.ai`. Run it once, as given, at the project's root. It ends 0 where the entry was taken, 1 where its install failed, and 3 where nothing was written."
},
"command_windows": {
"type": "string",
"description": "Present with `command`: the same line for every Windows shell, with `turnzero.cmd` where its head says `turnzero`. On Windows, run this one in `command`'s place, as given."
},
"command_npx": {
"type": "string",
"description": "The same line run through npx, `npx --no-update-notifier -y turnzero@<tag>` in place of `turnzero`, the tag `latest` on production's platform and `next` on every other. It is present exactly where `command` is. Run this line first, or `command_npx_windows` on Windows; it runs whether or not the command is installed. If your safety check refuses it, run `command` where `turnzero --version` responds, else `deploy_files` for a deploy or install the command. A person or a job may run any of the four forms (PLD-L0-94)."
},
"command_npx_windows": {
"type": "string",
"description": "`command_npx`'s line for every Windows shell, with `npx.cmd` where its head says `npx` (PLD-L0-94)."
},
"next": {
"type": "string"
}
},
"additionalProperties": false
},
"source_commit": {
"description": "The library commit this publish was read at. A project's folder manifest must record, per entry, the commit it was published from; the fact lives on the catalog rather than on any row, so it is returned here or it is unreachable (LC-07). Absent before the first publish.",
"type": "string"
},
"published_at": {
"description": "When this publish ran, ISO 8601. Distinct from an entry's own published_at, which is when that entry last changed. Absent before the first publish.",
"type": "string"
},
"note": {
"type": "string",
"description": "Present where `contains` matched no served entry's name or summary and `held_only` was not true: one line listing every served entry by name, so a word the library does not use still shows what it serves (LC-06)."
}
}
}
}
Shared contracts #
- Refusals: every refusal, by surface, with its cause and its remedy
- schemas/wire_error.schema.json
- schemas/wire_errors.json
- schemas/action_payloads.json (includes shared shapes)
- management_api_contract.md