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.

Automatic secret redaction

Every event emitted via createAgentActivityConnector or buildAgentActivityPayload runs inline secret scanning on free-form content subtrees before payload emission.

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

// Direct string redaction helper
const { value, classes } = redactSecretString('API key: AKIAIOSFODNN7EXAMPLE');
// -> value: 'API key: [redacted:aws_access_key_id]'

// Deep object redaction helper (non-mutating)
const { value: cleanObj, summary } = redactSecrets({
  tool: { name: 'bash', input: { command: 'export AWS_KEY=AKIAIOSFODNN7EXAMPLE' } }
});
// -> summary: { secrets_redacted: 1, classes: ['aws_access_key_id'] }

Zero-configuration privacy

You do not need to call redactSecrets manually when using the connector helper. The helper runs redaction on tool inputs, outputs, attributes, policy rationale, and event bodies automatically, attaching the per-event redaction summary to the envelope.

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 harness adapters — Pi, OpenCode, Antigravity / Gemini CLI, Factory AI Droid, or your own — where the harness 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.