Agent Passport

The Agent Passport (@lumenflow/agent, WU-3515, INIT-091 phase 2) is the canonical, framework-neutral product object for a registered agent. It covers seven attribute groups:

1. Stable agent identity and accountable owner
2. Purpose, capabilities, framework, deployment location
3. Agent, prompt, skill, and pack versions
4. Permitted tools, data scopes, and delegation rights
5. Authority ceiling, spend limit, and applicable policy
6. Evaluation, certification, health, and activity
7. Cryptographic provenance and complete change history

Every field that identifies a runtime, provider, or product is an opaque, caller-supplied label — this module never branches on the value of any such label, which is what keeps the contract and the registration SDK framework-neutral by construction: a negative test proves no vendor-name branch exists.

Registering an agent

Caution

registerAgentPassport is implemented in packages/@lumenflow/agent/src/passport/, but as of this writing it is not yet re-exported from the package’s public entry point or package.json exports map — import {registerAgentPassport} from '@lumenflow/agent' does not currently resolve. Treat the example below as the intended usage once that export gap is closed.

import { registerAgentPassport } from '@lumenflow/agent';

const passport = registerAgentPassport({
  content: {
    schema_version: 'agent_passport.v1',
    identity: { agent_id: 'agent-1', display_name: 'Release Agent', owner: 'platform-team' },
    purpose: {
      purpose: 'release-automation',
      capabilities: ['sbom-generation', 'dependency-scan'],
      framework: 'custom-runtime',
      deployment_location: 'ci-runner',
    },
    versions: {
      agent_version: '1.0.0',
      prompt_version: null,
      skill_versions: [],
      pack_versions: [{ name: 'operations-tooling', version: '1.4.0' }],
    },
    authorization: {
      permitted_tools: ['release:run'],
      data_scopes: ['release-artifacts'],
      delegation_rights: [],
    },
    governance: { authority_ceiling: 'release-worker', spend_limit: null, applicable_policy: [] },
    evaluation: {
      evaluation_status: 'unevaluated',
      certification: null,
      health: 'healthy',
      last_active_at: null,
    },
  },
  registeredAt: '2026-07-25T00:00:00.000Z',
  actor: 'platform-team',
});

passport.provenance.passport_digest; // sha256:...

Deterministic and idempotent

Passport issuance is a pure function of its input: the same content, timestamp, and actor always produce the same passport digest. Re-registering an unchanged agent — passing the previously issued passport back in as previousPassport alongside unchanged content — returns that exact previous passport untouched: no new change-history entry is appended, and the digest is identical, regardless of the registeredAt/actor supplied for the no-op call.

A content change always appends exactly one new, append-only change-history entry (issued on first registration, updated thereafter) recording at, actor, and the new content digest. History entries are never edited or removed.

Governance data, not enforcement

authority_ceiling, spend_limit, and applicable_policy are recorded on the passport as data only — this package does not enforce them. Enforcement of those values lives outside @lumenflow/agent; the passport is the record of what was declared, not the mechanism that checks it.

Ownership split

Dev owns the registration SDK and the passport-emitting contract. Fleet inventory, shadow-agent discovery, and any administrative UI over registered passports are Cloud-owned and out of scope for this package.

Related

• Contract spine — the shared error taxonomy and version-pin discipline this package’s sibling modules follow.