agents.5304135203.com Agent Build Guide

Canonical web page: https://agents.5304135203.com/ · Raw markdown: https://agents.5304135203.com/agents.md · Machine-readable: https://agents.5304135203.com/agents.json

Use this page as the source of truth for agent-facing architecture and local primitive contracts. Build against the local portal API, not directly against changing backing services.

Agent Build Source Of Truth

Last updated: 2026-03-24

Use this document and its rendered page as the source of truth for AI agents working with this LCARS/OpenCode portal deployment.

Canonical URLs:

web page: https://agents.5304135203.com/
raw markdown: https://agents.5304135203.com/agents.md
machine-readable JSON: https://agents.5304135203.com/agents.json
live capability/status JSON: https://agents.5304135203.com/agents/live.json
starter-kit discovery guide: https://agents.5304135203.com/kits
starter-kit discovery JSON: https://agents.5304135203.com/kits.json

Purpose

This deployment exposes a secure LCARS control surface for OpenCode and related operator workflows. Agents should build against stable local portal endpoints and treat backing services as replaceable implementation details.

Preferred shape:

browser -> portal local API -> adapters -> agent runtime / transcription backend / JmpKit / other services

Do not couple browser code directly to JmpKit primitives, private-network services, or raw local daemons unless there is a strong reason.

Topology Model

public portal shell: /lcars
public agent docs root: /
raw docs: /agents.md
machine-readable contract: /agents.json
live machine-readable capabilities: /agents/live.json
authenticated agent surface: /agent

Important rule:

the agent runtime is local-only and should be exposed publicly only through authenticated portal routing

Project Rules For Agents

treat the local portal API as the stable contract
keep JmpKit-specific details behind server-side adapters
choose transport based on topology, reachability, and communication pattern rather than defaulting to one transport
do not expose raw JmpKit primitive names or semantics into user-facing browser code unless needed
assume JmpKit primitives can change over time
prefer thin adapters and stable response shapes

External Resource Policy

When building features that may depend on external resources or external service URLs:

first ask the user whether they already have resource URLs they want used
if the user provides those URLs, prefer them
if the user does not provide any resource URLs, the agent should build or provision the needed resources
do not silently hardcode unrelated third-party resource URLs when the user has not requested them
keep externally supplied resource URLs behind local adapters where practical

JmpKit Context

JmpKit is cloud/back-end plumbing for agents. It is not an agent host. The intended model is:

[user] <-> [agent] <-> [jmpkit]

Relevant observed primitive direction:

q is the likely long-term coordination primitive
locke or locket is being dropped in favor of q
vmem may also be reduced or dropped in favor of q
protocol change is expected; agent adaptability is part of the model

Architectural consequence:

do not build this portal around direct locke or vmem assumptions
use local endpoints that can later map to q, ziphost, hubs-uws, billing, or other services

Starter Kits

The starter-kit archives are important learning artifacts for agents. They teach the primitives more directly than this portal contract page does.

starter-kit discovery page: /kits
starter-kit discovery JSON: /kits.json
canonical source site: https://jmpkit.com

Agent expectations:

read the relevant starter kit before implementing or integrating with a primitive
use the kits to understand the primitive contracts and patterns
search jmpkit.com for the relevant starter kit instead of assuming a fixed download path on this site
assume kit locations on jmpkit.com may change over time
do not assume every deployment uses every primitive directly just because a kit exists
build against the local portal API contract first, then map to the primitive that best fits the topology and workflow

Transport Selection Guidance

Agents should choose the communication method that best fits the actual topology and the kind of communication needed.

do not assume a private process or LAN service is internet-reachable
do not assume standard HTTP reachability already exists just because streaming is needed
use SSE when one-way HTTP event streaming is sufficient and an appropriate HTTP path already exists
use hubs-uws when low-latency duplex communication is useful, or when a private backend should participate without becoming internet-facing
if exposing a backend publicly would require significant new routing, DNS, TLS, proxying, or security work, consider whether hubs-uws or another non-public-facing approach is a better fit
ask what resources already exist before designing the transport layer

Local Primitive Layer

The local primitive layer is the desired long-term contract for the portal.

Current Live Local Endpoints

Health

GET /healthz
returns basic health for the deployment

Example:

{ "ok": true }

OpenCode Auth Public State

GET /api/opencode-auth/public-state
returns public auth-related state for the portal UI

OpenCode Auth Session

GET /api/opencode-auth/session
returns whether the current browser session is authenticated

Response shape:

{
  "authenticated": true,
  "method": "phrase",
  "expiresAt": 1774318629,
  "modeArmed": false
}

OpenCode Auth Login

POST /api/opencode-auth/login
authenticate via a supported method

Current supported methods in the portal codebase include:

security_key
totp
phrase
phone_code
email_code
recovery

Typical request:

{ "method": "phrase", "secret": "..." }

Typical response:

{
  "ok": true,
  "method": "phrase",
  "expiresAt": 1774318629,
  "launchPath": "/api/opencode-auth/launch",
  "lcarsPath": "/lcars"
}

OpenCode Auth Helpers

Also implemented:

POST /api/opencode-auth/webauthn/login/begin
POST /api/opencode-auth/webauthn/login/finish
POST /api/opencode-auth/phone-code/begin
POST /api/opencode-auth/phone-code/finish
POST /api/opencode-auth/email/begin
POST /api/opencode-auth/email/finish
GET /api/opencode-auth/email/consume
POST /api/opencode-auth/webauthn/register/begin
POST /api/opencode-auth/webauthn/register/finish
POST /api/opencode-auth/logout
GET /api/opencode-auth/launch
GET /api/opencode-auth/verify

Interfacer Public State

GET /api/interfacer/public-state
returns public job-queue state for the portal UI

Interfacer Private State

GET /api/interfacer/state
GET /api/interfacer/jobs
require either a valid LCARS session or the configured bearer token

Submit Agent Job

POST /api/interfacer/jobs
submits a job to the current local agent queue
requires either a valid LCARS session or the configured bearer token

Request:

{
  "prompt": "Summarize current state",
  "source": "web",
  "operator": "remote web"
}

Response:

{
  "ok": true,
  "job": {
    "id": "job_..."
  }
}

Target Stable Local Primitives

These are the preferred future local contracts. They are design targets and may not all be implemented yet.

Voice

POST /api/voice/sessions
POST /api/voice/sessions/:id/audio
GET /api/voice/sessions/:id/events

Intent:

browser records audio locally
portal API handles auth and upload
server forwards transcription to a private backend
transcript events may use SSE, hubs-uws, or another transport depending on topology and backend reachability

Agent Jobs

POST /api/agent/jobs
GET /api/agent/jobs/:id
GET /api/agent/jobs/:id/events

Intent:

unify the current interfacer queue behind a cleaner stable contract
allow future migration to JmpKit q without breaking the browser contract

Node Status

GET /api/node/status

Intent:

safe operational summary for the portal and related services

Publish

POST /api/publish

Intent:

publish app bundles through a backing service such as JmpKit ziphost

Stable Response Shapes To Preserve

Keep these shapes stable even if backing services change.

Job Shape

{
  "id": "job_123",
  "kind": "agent",
  "state": "queued",
  "summary": "Summarize current state",
  "detail": "optional longer text",
  "source": "web",
  "createdAt": "2026-03-24T00:00:00Z",
  "updatedAt": "2026-03-24T00:00:00Z"
}

Voice Session Shape

{
  "id": "voice_123",
  "state": "recording",
  "backend": "private-transcription-backend",
  "partial": "",
  "transcript": "",
  "startedAt": "2026-03-24T00:00:00Z"
}

Capabilities Shape

{
  "voice": true,
  "transcribe": true,
  "publish": true,
  "realtime": "sse"
}

Auth Expectations

public docs at /, /agents.md, /agents.json, and /agents/live.json should remain readable without auth
mutating control endpoints require either a valid LCARS session cookie or the configured bearer token where supported
do not publish secrets, bearer tokens, recovery phrases, or internal credentials in public docs

Browser Integration Guidance

browser code should call only local portal endpoints on this origin
browser code should not call raw JmpKit endpoints directly
browser code should not call private backend services directly
choose browser-facing transport based on actual reachability and communication needs

Backing Service Mapping

Current and future mapping style:

agent jobs -> local job adapter -> agent runtime
voice transcription -> private transcription backend
publish -> JmpKit ziphost or another publisher
future events/jobs persistence -> JmpKit q
realtime or duplex process communication -> hubs-uws when that best matches topology and communication needs
future media connectivity -> STUN/TURN host

Change Policy

This page is intended to be the main agent-facing source of truth.

When changing architecture or contracts:

update this document
update backing code
keep local API names stable where possible
prefer adapter changes over browser-contract changes

Short Summary For New Agents

this is a secure LCARS portal for remote agent control
the browser should talk only to local portal endpoints
the local portal API is the stable contract
JmpKit is backing fabric, not the browser contract
prefer q concepts over older locke assumptions
keep the agent runtime local-only
future voice transcription should go through the portal API to a private backend