Company OS External Adapter Lane

This is the first Company OS-native external-adapter contract. It is inspired by Paperclip's external adapter, but it is Company OS-native first and makes No Paperclip drop-in claim.

Product Contract

adapter_type = "external" means:

• Company OS does not run a server-side model for this wake.
• Company OS does not emit usage or costUsd for this wake.
• The external runner does the compute and writes results back through Company OS APIs, run events, task notes, connector sessions, and skills surfaces.
• The lane reuses existing company_agents.adapter_config rows and the verified-run timeline rather than creating a second ledger.

Capability declaration:

Capability	Value
supportsInstructionsBundle	true
supportsLocalAgentJwt	true
supportsSkills	true
requiresMaterializedRuntimeSkills	false
supportsModelProfiles	false

The runner, not Company OS, materializes desired skills. This keeps compute and runtime-specific files outside the server while preserving a durable desired state in the Company OS ledger.

Wake Modes

noop is the default. It records a cost-safe wake plan and returns immediately. Use this when an embodied local runner is already polling Company OS.

webhook sends a wake notification to url and then returns. The body shape is intended to be compatible with existing runner workers: payload template plus agent/run/context fields.

bridged is the live-mirroring mode. It is bounded by:

• claimGraceMs default 12000: if no runner claims the wake, degrade to webhook/noop-style completion.
• bridgedTimeoutMs default 600000: once claimed, finalize after runner silence.
• bridgedMaxMs default 3600000: absolute lifetime cap.
• pollIntervalMs default 1500: relay polling cadence.

These defaults are part of the safety contract: bridged wake behavior must not hang runs indefinitely.

Config Schema

The native schema is exposed at:

GET /api/company/external-adapter/contract

The schema has two UI groups:

• Wake: mode, url, method, headers, payloadTemplate, timeoutMs, claimGraceMs, bridgedTimeoutMs, bridgedMaxMs, pollIntervalMs.
• Runner: model, effort, maxTurnsPerRun, workspaceStrategy, instructionsFilePath.

Runner fields are hints for the external runner. Company OS stores them and reports them, but does not run a model because of them.

Config Diagnostics

The config diagnostics surface is intentionally adapter-specific so operators can test external wake configuration before assigning an agent to the lane.

Diagnostics are exposed at:

POST /api/company/external-adapter/diagnose

with either the config directly or { "adapterConfig": { ... } }.

Diagnostics:

• noop passes with an informational cost-safe check.
• webhook and bridged require an absolute http(s) URL.
• invalid URLs and unsupported protocols are errors.
• webhook/bridged configs without auth-like headers warn with external_webhook_unauthenticated.

Integration Points

This first slice deliberately stops at a safe contract and diagnostic surface. It reuses:

• company_agents.adapter_type and adapter_config
• markdown agent definitions and inline runtime declarations
• repo and Company OS skills
• connector accounts, sessions, and trigger subscriptions
• run execution events and verified-run output/cost badges
• model_gateway.rs for paid provider budget enforcement

Next implementation slice: make the worker dispatcher honor adapter_type = "external" by producing a no-model wake run, then add bridged relay endpoints for /progress/:runId and /complete/:runId.