v3.3.0

TinyCloud SDK 3.3.0 and CLI 1.3.0

Sharing

• tc share publish can publish a folder that has an index.html as a single self-contained page, and can store files as numbered versions of an artifact (--artifact). Pinned shares record which version they point to.
• Share errors now say what went wrong (space not ready, not signed in, no permission, not found, node unavailable, network) with distinct exit codes, instead of a generic "invalid argument". The share history is checked before sign-out, key rotation or replica login replaces its key, so unexpired shares are not lost. Opening a share in several browser tabs now uses one signing key, and the receiver key is kept so a reload keeps working.
• Share links and viewers: viewers on an older share SDK will not open shares that carry an artifact pin; update @tinycloud/share-sdk.

Signing in and agents

• Granting an agent access through OpenKey now asks the owner to approve every request, and the agent preset can no longer change an app's own code. Plain sign-in names the existing owner so OpenKey preselects the right key, waits until your space is ready, and keeps the browser callback open for five minutes. Cancelling a login no longer signs out an existing session.
• Agents can pick up apps a user installed, and tinycloud apps install <app> installs a catalog app's notes and tables into your space.
• tc delegation create confirms the delegation is active before printing it; list and info also show delegations signed by the session key; tc delegation revoke works from another profile or machine of the same account.
• Account commands check up front that the session may use the account space and say how to sign in again if not.

Reliability

• Busy and timeout answers from the node are retried automatically with a fresh signature each time. Turn off with --no-retry or TINYCLOUD_RETRY=0.
• Retry signals from the node are reported as specific errors instead of a generic network error. A failed conditional write is no longer reported as a conflict.
• Storage-full messages link to the account storage page.

Offline copies (replicas, beta feature)

• Sign-out denies local copies first and erases them safely, interrupted sign-outs finish on the next sign-out, storage size can be capped, and expired consent is reported with renewal guidance. tc replica report now only reads recorded state (see breaking changes).

SDK

• Vault entries support compare-and-swap writes (ifMatch, etag) and an optional check that an entry was written for its own key.
• Opt-in registryPolicy: "fail-closed" for host lookup and space creation (default unchanged).
• A change feed for key-value prefixes, a helper listMatching for partial-name listing, an off-node verifier for held credentials, and TinyCloudNode.signOut(); TinyCloudWeb.signOut() now ends the session on the instance.
• Delegations can be marked terminal (disableSubDelegation: true) so they cannot be passed on.

Also released: courier 0.2.0, mcp 0.7.0, operations 0.7.0, replica 0.3.0, share-sdk 1.2.0, share-envelope 1.2.0, server 2.5.7, vfs 0.2.7, web-sdk-wasm 1.7.7, node-sdk-wasm 1.7.8.

Breaking changes and behaviour changes

• Removed: DelegationManager.create() and .list(), TinyCloudNode.delegate() and .listDelegations(), TinyCloudWeb.delegate() and .listDelegations(), and the delegationManager option of the sharing service. They never worked against the node. Use delegateTo() and account.delegations.query().
• disableSubDelegation: true now throws instead of producing a delegation that can still be passed on.
• The tinycloud.kv/sync and tinycloud.kv/retain abilities must be granted by name; * no longer covers them. Custom implementers of the key-value service interface must add changes().
• Web share receiver: the ShareReceiverSessionRecordV1 type is gone and custody is now "persistent" | "memory".
• CLI: tc replica report --json no longer starts a runtime and returns replicas: []; read partitions[].pinned. --purge and --clear-pending are refused with exit 2 (REPORT_READ_ONLY).
• Courier: courier request now requires --verb, --target and --summary; existing broker token files are no longer used, so reconfigure the broker after signing in with gh.
• Node.js 20 or newer, as before.

---

CLI 1.3.0 in detail

Covers 1.2.5 → 1.3.0 (promoted from 1.3.0-beta.55). Requires Node.js 20 or later, unchanged from 1.2.5. Install with npm install -g @tinycloud/cli@1.3.0. Both tinycloud and tc are installed.

New

• Apps for agents.
  • tinycloud apps install <app_id> installs a pinned catalog app (today: the sample Health Log) into your applications space. It checks every file's size and hash first. Files you have edited are kept, and running it again is safe.
  • tinycloud knowledge list and tinycloud knowledge read <app_id> [concept] let an agent read the apps you installed.
  • tinycloud auth request --preset apps-agent [--app <app_id>] [--write] asks for exactly that access.
• Sharing.
  • Publish a folder that has an index.html as one self-contained page: tc share publish ./site/.
  • --artifact <id|new> publishes a file as a write-once version and pins the share to it. tc share versions <id> lists the versions.
  • .jsx and .tsx files are published with their own media types.
  • tc share history recover moves an unreadable share history aside without deleting it.
  • tc share publish --json reports whether the share was recorded in your history.
• Delegations work. tc delegation create, list and info now create and read real delegations. In 1.2.5 they always failed. tc delegation revoke <cid> also works from another profile or machine of the same owner.
• Busy nodes. The CLI retries automatically when the node says it is busy or timed out before applying anything: at most 4 tries in about 12 seconds. Use --no-retry or TINYCLOUD_RETRY=0 to turn this off. A write whose outcome is unknown is reported as such, so you can check before retrying.
• Sign-in.
  • tc auth login and tc init wait (up to 150 seconds) until your new space is ready, so your first command no longer fails with "Space not found".
  • The browser sign-in stays open for the full five minutes and prints a tip on how to finish if it takes a while.

Behaves differently from 1.2.5 (check scripts before upgrading)

• tc share error codes. Failures that used to be INVALID_ARGUMENT (exit 2) now have their own code:
  • AUTH_REQUIRED 3
  • PERMISSION_DENIED 5
  • NOT_FOUND or SPACE_NOT_READY 4
  • NETWORK_ERROR 6
  • NODE_UNAVAILABLE 7
  • NODE_REJECTED 1
• Node busy or timeout errors. These are now NODE_BUSY, REQUEST_TIMEOUT or OUTCOME_UNKNOWN (exit 7) instead of NETWORK_ERROR. A conditional KV write that hits a busy node is no longer reported as KV_CONFLICT.
• Cancelling a sign-in (Ctrl-C, or a signal to a non-interactive run) exits 130 CANCELLED, not 3.
• Sign-out, key rotation and replica sign-in protect your share history. auth logout, auth rotate, and auth login with replication refuse (exit 5, SHARE_HISTORY_UNEXPIRED or SHARE_HISTORY_UNAVAILABLE) when the profile still has unexpired shares. Add --force to proceed anyway.
• tc auth grant from an OpenKey owner now always asks the owner to approve in OpenKey. --yes no longer skips that approval. Grants are capped at 7 days. Without a terminal, it prints the approval URL and waits.
• tc auth login also asks for permission to list your delegations, so the OpenKey approval shows one more line.
• tc account … commands stop early with ACCOUNT_ACCESS_REQUIRED (exit 5) when the session lacks the access they need, and print the command that grants it.
• --preset apps-agent --write lets the agent change an app's notes, preferences and tables, but no longer its code or manifest.
• tc share publish --to anyone --action edit now fails (exit 2) instead of silently publishing a read-only link.
• --artifact needs a fresh sign-in if your profile signed in for sharing before this release: tc auth login --device --manifest builtin:share-publishing. Other sharing is unchanged.
• Pinned shares need a current Share viewer. An addressed share published with --artifact carries a pin that viewers built before this release refuse. share.tinycloud.xyz is current.
• Local replicas (beta).
  • tc replica report is read-only. --purge and --clear-pending exit 2 (REPORT_READ_ONLY). For a named replica, use tc replica reset --replica <name> --purge instead.
  • In --json, per-partition counts moved from replicas[].pinned to partitions[].pinned.
  • Sign-out is safer: it stops replicas first, and a sign-out that was interrupted resumes when you run it again.
• Storage-full errors link to https://account.tinycloud.xyz/storage.
• Install size. The package now includes jsdom. It loads only for folder publishing.

Courier (tc courier)

What it adds:

• Approvals and requests. courier request takes a verb (merge, deploy, publish, spend, other), a target and a summary. Merge requests carry the PR head commit and base (--head-sha, --base). courier approval checks the owner's decision once; each approval is single use.
• Guard and approved actions. courier guard (a Claude Code hook) refuses direct merge, deploy, publish and credential commands for a woken agent. courier run-approved <id> runs an approved merge with fixed arguments.
• Wake budget, pause, notifications. A per-thread daily wake budget, courier pause/resume, and --notify none|osascript|exec.
• Wake adapters and services. --wake paseo|claude|exec|none, --install-launchd, --install-systemd.
• Reader and sender for an isolated assistant. courier intake, courier outbox add, courier outbox serve, and --peers-owner <user|uid>.
• Share view: https://share.tinycloud.xyz/courier shows threads, approvals and orders.

Behaves differently from 1.2.5:

• An existing grant is refused with grant-incomplete until the owner runs courier init again.
• Merge requests need --head-sha (40 lowercase hex) and --base. Older requests without them can no longer be approved and must be filed again.
• Requests and approvals are checked against their verb and target, and use a stricter text alphabet (letters, digits, plain punctuation) with fixed length caps.
• The insecure-profile error code is now profile-permissions.
• --wake exec needs --unguarded. courier pair|revoke|init|pause|resume|watch are refused for a woken agent.
• The GitHub broker no longer uses stored broker token files. Configure the broker again after signing in with gh.

---