@agent-action-runner/http

Shared HTTP adapter utilities for Agent Action Runner.

This package is primarily for framework adapter authors. The official Express and Fastify adapters use it to keep request handling, response shapes, execution option handling, and error mapping consistent.

Experimental / pre-1.0.

Install

npm install @agent-action-runner/core @agent-action-runner/http

Most applications should install @agent-action-runner/express or @agent-action-runner/fastify instead of using this package directly.

HTTP Contract

Official HTTP adapters expose:

Method	Path	Description
`GET`	`/actions`	Lists action metadata.
`POST`	`/actions/:name/execute`	Executes one action.
`POST`	`/workflows/execute`	Executes a JSON workflow.

GET /actions intentionally omits schemas.

{
  "ok": true,
  "actions": [
    {
      "name": "delivery.searchJobs",
      "mode": "read",
      "description": "Search delivery jobs by status.",
      "approvalRequired": false
    }
  ]
}

Action execute request bodies use:

{
  "input": {
    "status": ["FAILED"]
  }
}

Workflow execute request bodies use:

{
  "workflowId": "workflow_1",
  "workflow": {
    "workflowName": "search-failed-jobs",
    "steps": []
  }
}

Security Boundary

HTTP adapters should resolve execution context from trusted server-side sources:

type AgentHttpAdapterOptions<Request> = {
  getUserId: (request: Request) => string | Promise<string>;
  getAllowedModes?: (request: Request) => readonly ActionMode[] | undefined | Promise<readonly ActionMode[] | undefined>;
  getApprovalToken?: (request: Request) => string | undefined | Promise<string | undefined>;
  getApprovalContext?: (request: Request) => ApprovalContextOverrides | undefined | Promise<ApprovalContextOverrides | undefined>;
  getMetadata?: (request: Request) => Readonly<Record<string, unknown>> | undefined | Promise<Readonly<Record<string, unknown>> | undefined>;
  allowClientExecutionOptions?: boolean;
};

By default, client-supplied allowedModes, approvalToken, approvalContext, and metadata are ignored. They are passed through only when allowClientExecutionOptions: true is set.

Adapter Author Example

import {
  createActionListResponse,
  executeHttpAction,
  executeHttpWorkflow,
  mapAgentRunnerError,
  resolveAgentHttpRequestContext,
} from '@agent-action-runner/http';

router.get('/actions', (_req, res) => {
  res.json(createActionListResponse(runner));
});

router.post('/actions/:name/execute', async (req, res) => {
  try {
    const context = await resolveAgentHttpRequestContext(req, options);
    const result = await executeHttpAction(runner, req.params.name, req.body, context);
    res.json(result);
  } catch (error) {
    const mapped = mapAgentRunnerError(error);
    res.status(mapped.statusCode).json(mapped.response);
  }
});

router.post('/workflows/execute', async (req, res) => {
  try {
    const context = await resolveAgentHttpRequestContext(req, options);
    const result = await executeHttpWorkflow(runner, req.body, context);
    res.json(result);
  } catch (error) {
    const mapped = mapAgentRunnerError(error);
    res.status(mapped.statusCode).json(mapped.response);
  }
});

Public Helpers

resolveAgentHttpRequestContext(request, options)
createActionListResponse(runner)
executeHttpAction(runner, actionName, body, context)
executeHttpWorkflow(runner, body, context)
mapAgentRunnerError(error)

Response Shapes

Success:

{
  "ok": true,
  "result": {}
}

Action list:

{
  "ok": true,
  "actions": []
}

Error:

{
  "ok": false,
  "error": {
    "code": "SCHEMA_VALIDATION_FAILED",
    "message": "Action \"delivery.searchJobs\" failed input schema validation."
  }
}

Error Mapping

Core Error	HTTP Status	Code
`ActionNotFoundError`	`404`	`ACTION_NOT_FOUND`
`SchemaValidationError`	`400`	`SCHEMA_VALIDATION_FAILED`
`InvalidStepReferenceError`	`400`	`INVALID_STEP_REFERENCE`
`ModeNotAllowedError`	`403`	`MODE_NOT_ALLOWED`
`ApprovalRequiredError`	`403`	`APPROVAL_REQUIRED`
`PolicyRejectedError`	`403`	`POLICY_REJECTED`
unknown error	`500`	`INTERNAL_ERROR`

WorkflowExecutionError maps from its cause when possible. Otherwise it returns 400 with WORKFLOW_EXECUTION_FAILED.

License

Apache-2.0