@forgezero/agent 0.1.31 → 0.1.33

package/README.md

@@ -17,14 +17,17 @@ The one public package installs both commands. Keeping bootstrap and the daemon
 in one version prevents a newly installed `fz` from provisioning a different
 agent protocol.
 
-The operator command launches a platform, runs custody ceremonies, inspects
-status, wraps processes, and installs the daemon:
+The operator command starts browser-first platform genesis, inspects status,
+wraps processes, and installs the daemon. Genesis opens the one-use founder
+invitation, waits for the new passkey account to approve this CLI through device
+authorization, then continues custody in the browser. Passkey PRF output and
+both recovery phrases never enter the terminal:
 
 ```bash
 fz keys
 fz status
-fz genesis --mode 2-of-3
-fz unlock
+fz genesis --mode 2-of-3 --api https://api.example --app https://console.example
+fz unlock --phrase-file /secure/offline-phrase.txt # run once per participating custodian
 ```
 
 Install the service explicitly:
@@ -136,6 +139,44 @@ are generated adapters. They contain no independent architecture or progress.
 by hand. Tools and skills remain optional execution aids; accepted decisions and
 status live in the repository and therefore survive switching AI agents.
 
+## Browser-authorized project control
+
+Sign in from any checkout with the public CLI. The terminal displays a device
+code and the browser approves it in the selected tenant realm:
+
+```bash
+fz login --api https://api.forgezero.net --realm acme
+fz whoami
+fz ui routes --json
+```
+
+The short session is stored by API origin and realm in an owner-only local file.
+It is never committed to `.fz/config.json`. A protected mutation opens a browser
+page for passkey or TOTP proof and then replays the exact request once; the CLI
+has no privileged server mode.
+
+Any ordinary website operation is available to developers and AI agents through
+the same API and access matrix:
+
+```bash
+fz ui routes pipeline
+fz ui get /workspace/pipelines --query projectKey=my-project
+fz api post /workspace/pipelines/status \
+  --data '{"pipelineKey":"pl_…","enabled":false}'
+generate-request | fz api post /workspace/action --data -
+```
+
+Only realm-relative paths are accepted, so the saved session cannot be forwarded
+to another origin. Inline JSON, stdin and JSON files are supported. Use
+`fz logout` to revoke the remote session and remove the local copy.
+
+`fz ui routes --json` reads the action catalog from the API's enforced access
+matrix. It lists only the current account's current realm, stage and grants, so
+developers and AI agents can discover the available control surface without a
+copied CLI command list or a visit to the website. Execute any listed action
+with `fz ui <method> <path>`; sensitive actions open the same fresh-proof flow
+as the website and replay the exact request once.
+
 ## Deployment definitions
 
 A repository may commit `.fz/deploy.json` with its own profiles, prerequisite
@@ -155,6 +196,20 @@ fz deploy check
 fz deploy sync
 ```
 
+After sign-in, create and operate the durable pipeline from the same checkout.
+The project defaults to `.fz/config.json`; compute/profile attachments remain
+control-plane state rather than fields in the deploy file:
+
+```bash
+fz deploy connect --provider github --repository acme/web \
+  --clone-url https://github.com/acme/web.git --auth public \
+  --target compute-eu@api --target compute-us@api
+fz deploy list
+fz deploy runs --pipeline <pipeline-key>
+fz deploy release --pipeline <pipeline-key> \
+  --revision <full-40-character-commit> --wait
+```
+
 `init` refuses to invent a generic release or health check: both generated steps
 exit non-zero until the project replaces them. `check` validates the published
 v2 schema and active software coordinates, then prints a formatting-independent
@@ -209,7 +264,7 @@ only claims assigned to its enrolled hostname, then passes
 the fixed claim over a local Unix socket to a narrowly privileged root helper.
 The helper can materialize the audited QEMU profile; it cannot clone a project,
 read Vault data, accept arbitrary commands, or retain tenant credentials. Root
-SSH is an operator-only platform-genesis/recovery path, not the normal tenant
+SSH is an operator-only platform recovery path, not the normal tenant
 dispatch mechanism.
 
 New guests also call this same public `fz agent install --apply --enrol` path

package/dist/agent-heartbeat.d.ts

@@ -1,6 +1,7 @@
 import type { NodeKeyPair } from '@forgezero/runtime/identity';
 import { type AgentRelease } from './agent-update';
-import { type AgentUpdateResponse } from './agent-update-helper';
+import { type AgentUpdateReceipt, type AgentUpdateResponse } from './agent-update-helper';
+import type { AgentOperationTelemetry } from './telemetry-runtime';
 export interface AgentObservation {
     version: string;
     os: {
@@ -9,12 +10,18 @@ export interface AgentObservation {
     };
     architecture: string;
     mode: 'attested' | 'enrolled';
+    update?: AgentUpdateReceipt;
 }
 export interface AgentHeartbeatResponse {
     ok: true;
     nodeKey: string;
     intervalSeconds: number;
     desiredAgentRelease?: AgentRelease;
+    desiredAgentUpdate?: {
+        attemptId: string;
+        leaseExpiresAtTs: number;
+        release: AgentRelease;
+    };
 }
 export interface AgentHeartbeatOptions {
     apiUrl: string;
@@ -26,14 +33,17 @@ export interface AgentHeartbeatOptions {
     fetch?: (input: URL, init: RequestInit) => Promise<Response>;
     requestTimeoutMs?: number;
     observation?: () => AgentObservation;
+    receiptPath?: string;
+    now?: () => number;
     /** Stop new lifecycle/deploy claims and await current jobs before replacement. */
     prepareUpdate?: (release: AgentRelease) => Promise<void>;
     /** Restart the drained current process if staging is refused before activation. */
     recoverUpdate?: (cause: unknown) => Promise<void> | void;
-    applyUpdate?: (release: AgentRelease, currentVersion: string) => Promise<AgentUpdateResponse>;
+    applyUpdate?: (release: AgentRelease, currentVersion: string, attemptId: string) => Promise<AgentUpdateResponse>;
     setTimer?: (callback: () => void, ms: number) => unknown;
     clearTimer?: (handle: unknown) => void;
     onEvent?: (event: string, detail?: unknown) => void;
+    telemetry?: AgentOperationTelemetry;
 }
 export declare function observeAgentHost(version?: string, mode?: AgentObservation['mode'], osRelease?: string, architecture?: NodeJS.Architecture): AgentObservation;
 /** One PQ-authenticated observation and optional supervised update decision. */