Connect flow: local and cloud

[korivi-CraftOS]

Connect had a procedure but not a shape, and then a shape but nothing behind it. It is now the five gates the journey names, in order — and code that walks them.

Select App → Verify Identity → Owner Credential → Check Grant → Operate

Local and cloud, in one surface

A remote app is addressed by URL, in the commands that already exist:

a2app https://kanban.example.com                 the app's root screen
a2app https://kanban.example.com whoami          your grant
a2app https://kanban.example.com board cards     walk to an entity

There is no connect verb and no remote mode. a2app is the protocol client; where the app runs is the URL's business. Every operate command works against a remote app unchanged, because none of them ever needed the app's files.

Previously the CLI built exactly one base URL, hardcoded to 127.0.0.1, so the flow the skill described could not be walked at all.

The boundary is now structural

"Operated but never modified" was a rule an agent had to keep. It is now one it cannot break.

agent-app https://kanban.example.com promote
→ https://kanban.example.com is a remote app — it can be operated, not modified.
  Building, evolving and lifecycle commands act on an app's files, which are on
  its own host. Use `a2app https://kanban.example.com …` to operate it.        (exit 2)

A remote target carries no dir. loadProject — which every build and lifecycle command goes through — refuses a URL outright and names the command that does work. There is no runtime policy check to talk past, because there is nothing for promote or toolkit-sync to act on.

This falls out of the framework's existing split rather than adding to it: agent-app needs an app's files, a2app needs a URL and a credential. Connect was already the shape of that split; it just had not been pointed anywhere.

The identity gate runs before the first request

What answers a URL is not established by the URL answering. Every remote connection verifies, in this order:

1. the a2app: true marker — otherwise the fields below are read out of a document that does not mean them
2. the exact protocol version, not its major — 0.1 and 0.2 are different contracts, and the client accepts only what it actually speaks
3. app.id against what that origin returned the first time

⚠ First contact with https://kanban.example.com — pinning app.id "kanban".

→ https://kanban.example.com now identifies as "not-kanban", but was pinned to
  "kanban". Refusing to operate a different app than the one this origin was
  known for.                                                                   (exit 2)

An origin that starts answering as something else is refused, never followed. That is the failure worth catching, because it looks exactly like success — the requests still work, against something else.

The credential never comes from the app

Source	Use it for
A2APP_TOKEN	one app for one run — how a harness hands an agent a credential
credentials.json in the framework home	several apps across runs, keyed by origin (an appId entry beats a bare one)

The environment wins over the store. The local .principal password exchange is not reachable from a remote target: posting a user's password to someone else's host is precisely the ambient authority this flow exists to prevent.

Verification

Driven end to end against a live app (apps/playground) over a URL:

	Result
identity — first contact pins the id	✅
the walk — root screen, next-move hints echo the URL	✅
whoami with A2APP_TOKEN	✅
data schema — name comes from verified identity, not a manifest	✅
data people list — credential read from the store	✅
agent-app <url> promote	✅ refused, exit 2
tampered pin	✅ refused, exit 2

framework/cli/test/connect.test.mjs adds 21 checks over addressing (including that a Windows path is not mistaken for a URL), the boundary refusal, cache isolation between origins, credential precedence, and all four gate failures — no identity document, unknown protocol, missing app.id, changed app.id.

pnpm -r build, pnpm -r typecheck and pnpm -r test are clean; conformance 59/59.

Also in this PR

The skill was corrected against what the code actually does before any of it was written, which is how two of the above were found:

• Gate 38 said to recognise the protocol's MAJOR version. The client accepts an exact list and conformance asserts protocol: "0.1" outright, so a 0.2 app passed the gate and was then refused by the client it was handed to.
• Gate 38's app.id check had nothing to run on given a link or URL — there was no expected id to compare. It pins instead, and now the CLI does the pinning.
• The intersection ceiling was written as a guarantee in the present tense. Nothing implements it: a grant is checked on its own scopes and no adapter reads the acting user's token. Marked deployed-mode.

Plus: how is not always present and a hint written for the app's owner is not addressed to a guest; a whoami 401 does not mean nothing is reachable, so describe's per-level access is named as the authority; scopes arrives with * pre-expanded; the token headers are named; and a refusal table maps each code to the gate it returns you to.

Framework tooling context removed, as asked: the named list of local commands, the manifest.json / 127.0.0.1 mechanics, and the importer cross-reference. The boundary is stated as a rule rather than as a tour of the tools an agent must not use. One limit worth naming: all six skills install as a single tree, so modify still sits beside connect describing the local lifecycle — this removes the tour from connect, it cannot remove the framework from the agent's context.

Found by pointing it at a deployed app

Merging main brought #2's host allowlist: an adapter binds loopback and answers only on hostnames it is configured for. That is correct, and it is the first thing a cloud-hosted app does to a connecting agent — behind a proxy or tunnel the app receives its public hostname in Host and refuses it until its own config names it.

Pointing the new remote path at that case reported "Not an Agent App", which is false. Two causes, both fixed here:

identity() tested the marker without the status — in both SDKs. Every adapter error envelope carries a2app: true (it is how a client knows a refusal came from the app rather than from something in front of it), so a 403 forbidden_host was accepted as an identity document. What came back had no protocol and no app.id, so the caller reported whichever it touched first — unsupported protocol "undefined". A deployed app hits this on its very first request. The TypeScript and Python clients had the same test and are fixed together.

The refusal is now named. With the status honoured the failure was honest but still opaque, so the failure path reads the refusal once and says which host the app does not answer to, that the app is real and running, and that the fix is the owner's:

→ https://kanban.example.com is an Agent App, but it does not answer to that
  hostname. It replied 403 forbidden_host … the app's adapter needs
  "kanban.example.com" in its allowedHosts. Nothing you can send will change
  the answer.

An agent told "not an Agent App" retries elsewhere. An agent told this reports something its user can act on. A 401 on the identity document is named too — that document is unauthenticated by design, so a refusal there is a proxy or a tunnel's own auth, not the app. Diagnosis never changes what is refused; it only says why.

Deploying an Agent App for others to reach therefore means setting allowedHosts (or an allowedOrigins entry carrying the host) to the name it is served under. The skill documents this.

Still open, deliberately

whoami requires a credential unconditionally while an uncredentialled read is permitted on a single-user app, so a tokenless agent gets a 401 from whoami and can still read. Changing that is a protocol decision about what whoami owes an anonymous caller, not a bug to resolve quietly. The skill documents the current behaviour accurately either way.

The related fix to whoami's bare 401 is in #5 and does not block this.