Connectors

Build a JS/TS connector.

Use the shared portal client when an internal agent, MCP surface, hook adapter, or governed capability needs to emit signed agent_activity.v1 events.

Minimal connector

The helper handles session state, payload validation, signing, idempotency, redaction, and provenance fields.

js
const { createAgentActivityConnector } = require('@autodevops/verifier-portal-client');

const connector = createAgentActivityConnector({
  dryRun: true,
  source: {
    kind: 'custom_connector',
    name: 'internal-agent-connector',
    version: '0.1.0',
  },
  provenance: {
    source_classification: 'customer_internal',
    connector_id: 'internal-agent-connector',
    connector_version: '0.1.0',
    capability_id: 'shell-command-preview',
    capability_version: '1.0.0',
    policy_pack_id: 'regulated-baseline',
    policy_pack_version: '2026-05-16',
  },
});

await connector.startSession({ session_id: 'custom-session-1' });
await connector.emitToolFinished({
  tool: {
    name: 'shell',
    action: 'exec',
    command_preview: 'npm test',
  },
  outcome: {
    status: 'succeeded',
    summary: 'Tests passed.',
  },
});
await connector.finishSession({ status: 'succeeded' });

Copyable example

The executable example is packages/verifier-portal-client/examples/custom-connector.js.

Live ingest

Switch from dry run to signed posting after the portal endpoint and shared secret are configured.

bash
export AUTODEVOPS_PORTAL_INGEST_ENDPOINT="https://portal.example.com/api/verification-portal/ingest"
export AUTODEVOPS_PORTAL_INGEST_SECRET="shared-hmac-secret"
export AUTODEVOPS_TEAM_ID="00000000-0000-4000-8000-000000000000"
  • Use dryRun: true during local connector development.
  • Use failOpen: true only for ingest-only telemetry that must not block the agent.
  • Do not fail open for approval, destructive execution, secret access, or protected branch operations.
  • Attach source and connector provenance before live posting so portal evidence is reviewable.

When to use it

The connector helper is deliberately narrow. It is not a general workflow engine.

  • Use it for internal agents that need to write signed events into AutoDevOps Cloud.
  • Use it for custom governed capabilities that need session and approval evidence.
  • Use it for third-party agent adapters where the agent can emit lifecycle or tool-call data.
  • Do not use it as an inline LLM proxy. AutoDevOps ingests session data; it does not sit in the model request path.