hephaestus-network

# Hephaestus Agent Workforce Network

The active host LLM staffs the task. Agentlas Core federates content menus from
registered Local, owner Cloud, and public Hub inventory. No source and no
deterministic layer is the decision-maker or a server-side LLM executor.

Source scopes are exact:

- `network`: Local + Cloud + Hub;
- `local`: registered Local packages only;
- `cloud`: the signed-in owner's Cloud packages only;
- `hub`: public Hub packages only.

Before an unpinned search uses the Local source, Core refreshes every active
registered source folder and creates a new immutable release when its safe
content snapshot changed. This is discovery freshness; a prepared or
goal-bound roster remains pinned to its exact release. `network reindex` is a
rebuildable card-cache operation and is not required to refresh a registered
Local release. New folders still require explicit `local-register`.

Public demos and distribution proof use explicit `hub` scope. They must not use
private Local/Cloud inventory as evidence of public availability.

## Resolve the runner and sign in

Network can query owner Cloud and public Hub inventory, so establish the same
saved Agentlas session before staffing:

```bash
RUNNER=""
for c in \
  "$HOME/.agentlas/runtime/current/bin/hephaestus" \
  ./bin/hephaestus
do [ -x "$c" ] && RUNNER="$c" && break; done
if [ -z "$RUNNER" ]; then
  for cache in \
    "$HOME/.claude/plugins/cache/agentlas-core-engine/hephaestus" \
    "$HOME/.codex/plugins/cache/agentlas-core-engine/hephaestus"; do
    newest="$(ls -d "$cache"/*/bin/hephaestus 2>/dev/null | sort -V | tail -1)"
    [ -n "$newest" ] && [ -x "$newest" ] && RUNNER="$newest" && break
  done
fi
if [ -n "$RUNNER" ] && [ "${HEPHAESTUS_AUTH_AUTOPOPUP:-1}" != "0" ]; then
  "$RUNNER" auth ensure --timeout 180 >/dev/null 2>&1 || true
fi
```

The browser opens only when no reusable local sign-in exists. In CI or another
headless environment, set `HEPHAESTUS_AUTH_AUTOPOPUP=0`.

## Required MCP sequence

First confirm the typed tool menu contains `workforce.preflight_work_order` and
that its `_meta.protocolVersion` is at least `2026-08-20.1`. If the tool is
absent, the host is still attached to a preflight-less runtime. Do not fall back
to model-authoring the strict wire WorkOrder and do not retry the same invalid
call. Return the machine-readable boundary
`workforce_protocol_upgrade_required`; let the runtime's normal verified
auto-update finish, then reload the host/MCP session. An explicit
`hephaestus hep-update` remains an operator action, never an implicit skill
side effect.

Use the Agentlas Core Workforce contracts in this order:

```text
workforce.preflight_work_order(taskBrief=..., roles=..., edges=...)
workforce.search_candidates(workOrderRef=..., sourceScope="network")
workforce.expand_candidates(selectionSessionId=..., candidates=[{slotId, candidateOrdinal}])
workforce.validate_selection(decision={selectionSessionId, decisionAuthor, assignments})
workforce.prepare_execution(selection=..., federatedSelectionDigest=..., projectDir=..., goalId=activeGoalId?, fullDossier=false)
workforce.validate_execution_receipt(receipt=..., executionPlan=..., toolInventory=...)
```

Call these exact typed tools directly. Do not enumerate, serialize, print, or
search the host's complete `ALL_TOOLS` registry: the sequence and tool names are
already specified here, and dumping unrelated schemas spends context without
improving staffing.

The source-internal `workforce.fetch_runtime_bundle` call is performed by Core
from the pinned original source session/digest. The host must not call it
directly or replace it with a slug/`latest` lookup.

The default search response is a projected decision menu. Preserve its source
receipts and `selectionSessionId`, but do not echo that projection as
`federationResult`; Core resolves and revalidates the full pinned result by
session. The final receipt call is local, bounded, and read-only. It validates
host-produced evidence and never executes workers or creates a receipt.

The current CLI equivalent is `workforce search --scope network`. A host adapter
that does not yet expose typed `sourceScope` must report that wiring gap; it
must not silently call public Hub-only search and label it Network. Do not call
the legacy lexical router first. Do not turn install count, ratings, invocation
history, source precedence, or a deterministic top score into the staffing
decision. If a source is unavailable, preserve its finite failure receipt.

## 1. Perform job analysis

Act as the active top-level orchestrator. Convert the user's task into one
compact semantic draft for `workforce.preflight_work_order`. Core compiles it
into the exact redacted `agentlas.workforce-work-order.v1`, generates finite
WorkOrder/slot/artifact identifiers, fills omitted empty arrays, pins the
ontology version, validates the privacy boundary, and returns a one-hour
`workOrderRef`. Keep raw local files, secrets, memory, and private prompt details
on the host. Create one `roles` entry per materially distinct responsibility.
Each role may identify:

- semantic role/community and required skill or knowledge concepts, written as plain
  English phrases when no ontology id is obvious — Core normalizes them into
  schema-valid concept ids and reports every rewrite as `normalizedConcepts`.
  Only these semantic communities, roles, skills, and knowledge may narrow menu
  fit;
- execution requirements such as required MCP/tool capabilities, runtime,
  language, modality, and required/forbidden authority. Include these only when
  the requested action genuinely needs host proof. They never filter, rank, or
  exclude semantic candidates; Core carries them into the ExecutionContext and the host
  validates them against its actual tool inventory, capability binding plan,
  permission policy, and invocation receipt after selection;
- collaboration edges by 1-based role ordinal. An edge is a declaration of
  handoff, never a qualification requirement.