@sdlcagent/agent-sdk 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,136 @@
+# @sdlcagent/agent-sdk
+
+Contract library for Sage platform agents. Provides the HTTP server scaffold, the
+`ContextEnvelope` / `ResultEnvelope` contract types (validated with Zod), structured
+logging, and error types that every Sage agent runtime is expected to implement
+against.
+
+## Install
+
+```
+npm install @sdlcagent/agent-sdk
+```
+
+## Quick start
+
+An agent implements a single handler — `(ctx: ContextEnvelope) => Promise<ResultEnvelope>`
+— and hands it to `AgentServer`, which exposes `/invoke`, `/health`, `/ready`, and `/start`
+over HTTP.
+
+```ts
+import { AgentServer, type AgentHandler } from '@sdlcagent/agent-sdk';
+import manifest from './agent.manifest.json';
+
+const handler: AgentHandler = async (ctx) => {
+  // ctx is a validated ContextEnvelope
+  return {
+    status: 'SUCCEEDED',
+    summary: 'Did the thing',
+    output_data: { result: 42 },
+  };
+};
+
+AgentServer.start({ manifest, handler });
+```
+
+`agent.manifest.json` must contain at least `agent_id` and `version`.
+
+### Endpoints
+
+| Method | Path      | Purpose                                                            |
+| ------ | --------- | ------------------------------------------------------------------- |
+| POST   | `/invoke` | Parses the request body as a `ContextEnvelope`, runs `handler`, validates and returns a `ResultEnvelope`. Never throws over HTTP — failures come back as `status: "FAILED"` with a 200. |
+| GET    | `/health` | Returns `{ status, agent_id, version, image_digest }`.               |
+| GET    | `/ready`  | Returns `{ status: "ready" }`.                                       |
+| POST   | `/start`  | Injects per-tenant runtime env vars (`{ env_vars: {...} }`) before the first `/invoke`. |
+
+### Configuration (env vars)
+
+- `AGENT_PORT` — port to listen on (default `8080`)
+- `AGENT_TIMEOUT_MS` — per-invocation handler timeout (default `300000`)
+- `LOG_LEVEL` — `debug` | `info` | `warn` | `error` (default `info`)
+
+A `.env` file in the process working directory is loaded automatically on import.
+
+## Envelopes
+
+### ContextEnvelope
+
+The validated input to every agent invocation (`parseContextEnvelope` is called
+internally by `AgentServer`, but is exported for standalone use):
+
+```ts
+import { parseContextEnvelope, type ContextEnvelope } from '@sdlcagent/agent-sdk';
+
+const ctx: ContextEnvelope = parseContextEnvelope(req.body);
+```
+
+Key fields: `org_id`, `project_id`, `team_id`, `run_id`, `step_id`, `workflow_type`,
+`run_mode` (`'CREATE' | 'MODIFY_ENHANCE'`), `trigger`, `work_item_context`,
+`policy_snapshot`, `prompt_refs`, `redaction_profile`, `memory_refs?`, `agent_config`,
+`log_callback_url`, `step_token`.
+
+Throws `ContextEnvelopeParseError` (code `CONTEXT_INVALID`) on validation failure.
+
+### ResultEnvelope
+
+The validated output every handler must resolve to:
+
+```ts
+import { validateResultEnvelope, type ResultEnvelope } from '@sdlcagent/agent-sdk';
+```
+
+Key fields: `status` (`'SUCCEEDED' | 'FAILED' | 'HITL_REQUIRED'`), `summary`,
+`output_data?`, `action_requests?`, `artifacts_created?`, `critic_signal?`,
+`hitl_reason?`, `hitl_options?`, `remember?`, `agent_summary?`, `next_step_hint?`,
+`metrics?`.
+
+Throws `ResultEnvelopeValidationError` (code `OUTPUT_BUILD_FAILED`) on validation failure.
+
+## Errors
+
+`AgentError` is the base error type for agent handlers, carrying a stable `code`,
+a `retryable` flag (derived automatically per code unless overridden), and an
+optional `detail` payload:
+
+```ts
+import { AgentError } from '@sdlcagent/agent-sdk';
+
+throw new AgentError('MODEL_ERROR', 'LLM returned garbage');
+```
+
+Codes: `CONTEXT_INCOMPLETE`, `CONTEXT_INVALID`, `MODEL_ERROR`, `MODEL_REFUSED`,
+`ACTION_FORBIDDEN`, `WORK_ITEM_PARSE_ERROR`, `OUTPUT_BUILD_FAILED`, `TIMEOUT`,
+`UNEXPECTED`, and the Model Rail gateway codes `INVALID_REQUEST`,
+`BUDGET_EXCEEDED`, `PURPOSE_NOT_ALLOWED`, `POLICY_NOT_FOUND`. Any error thrown out
+of a handler is caught by `AgentServer` and turned into a `FAILED` `ResultEnvelope`.
+
+## Logging
+
+`logger` writes structured JSON lines to stdout and threads run context
+(`run_id`, `org_id`, `project_id`, `step_id`, `agent_id`) through
+`AsyncLocalStorage`, so any log call inside a handler automatically carries it:
+
+```ts
+import { logger } from '@sdlcagent/agent-sdk';
+
+logger.info({ event: 'DOING_WORK' });
+
+await logger.time('llm_invoke', async () => {
+  // logs STEP_START / STEP_END / STEP_ERROR with duration_ms
+});
+```
+
+`emitLog(ctx, phase, message, opts?)` posts a log line to the run's
+`log_callback_url` (best-effort, swallows errors) using one of the fixed
+`AGENT_PHASES`: `context_parse`, `llm_invoke`, `llm_complete`, `critic_tier1`,
+`critic_tier2`, `tool_call`, `artifact_write`, `result_emit`.
+
+## Development
+
+```
+npm run build         # compile to dist/
+npm test              # run the jest suite
+npm run test:coverage
+npm run typecheck
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdlcagent/agent-sdk",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Contract library for Sage platform agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",