@agent-os-sdk/client 0.7.11 → 0.7.13

package/dist/modules/agents.js

@@ -43,26 +43,35 @@ export class AgentsModule {
     }
     /**
      * Create a new agent.
+     * Backend only accepts `name` per CreateAgentRequest DTO.
      * @example
      * ```ts
+     * const { data: agent } = await client.agents.create({ name: "My Agent" });
+     *
+     * // With idempotency (safe to retry)
      * const { data: agent } = await client.agents.create({
      *   name: "My Agent",
-     *   description: "Does cool stuff"
+     *   idempotency_key: "unique-key"
      * });
      * ```
      */
     async create(body) {
+        const headers = { ...this.headers() };
+        if (body.idempotency_key) {
+            headers["X-Idempotency-Key"] = body.idempotency_key;
+        }
         return this.client.POST("/v1/api/agents", {
-            body,
-            headers: this.headers(),
+            body: { name: body.name },
+            headers,
         });
     }
     /**
      * Update an existing agent.
+     * Uses PATCH per backend AgentsController.
      */
     async update(agentId, body) {
-        return this.client.PUT("/v1/api/agents/{agentId}", {
-            params: { path: { agentId } },
+        return this.client.PATCH("/v1/api/agents/{id}", {
+            params: { path: { id: agentId } },
             body,
             headers: this.headers(),
         });
@@ -121,10 +130,20 @@ export class AgentsModule {
      * Publish a new version (bundle) of the agent.
      * @param agentId The agent UUID
      * @param graph_spec The graph specification to publish
-     * @param options Optional settings: version_label for tagging, set_as_live to make this the active version
+     * @param options Optional settings: version_label for tagging, set_as_live to make this the active version, idempotency_key for safe retries
      * @returns Bundle response with version details
+     * @example
+     * ```ts
+     * const { data: bundle } = await client.agents.publish(agentId, graphSpec, {
+     *   idempotency_key: "publish-unique-key"
+     * });
+     * ```
      */
     async publish(agentId, graph_spec, options) {
+        const headers = { ...this.headers() };
+        if (options?.idempotency_key) {
+            headers["X-Idempotency-Key"] = options.idempotency_key;
+        }
         return this.client.POST("/v1/api/agents/{id}/publish", {
             params: { path: { id: agentId } },
             body: {
@@ -132,7 +151,7 @@ export class AgentsModule {
                 version_label: options?.version_label ?? null,
                 set_as_live: options?.set_as_live ?? true
             },
-            headers: this.headers()
+            headers
         });
     }
     // ======================== Bundles ========================

package/dist/modules/credentials.d.ts

@@ -66,6 +66,7 @@ export declare class CredentialsModule {
     }): Promise<APIResponse<Credential>>;
     /**
      * Update a credential.
+     * Uses PATCH per backend CredentialsController.
      */
     update(credentialId: string, body: {
         name?: string;

package/dist/modules/credentials.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/modules/credentials.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/modules/credentials.ts"],"names":[],"mappings":"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"}

package/dist/modules/credentials.js

@@ -42,9 +42,10 @@ export class CredentialsModule {
     }
     /**
      * Update a credential.
+     * Uses PATCH per backend CredentialsController.
      */
     async update(credentialId, body) {
-        return this.client.PUT("/v1/api/credentials/{id}", {
+        return this.client.PATCH("/v1/api/credentials/{id}", {
             params: { path: { id: credentialId } },
             body,
             headers: this.headers(),

package/dist/modules/crons.d.ts

@@ -54,6 +54,7 @@ export declare class CronsModule {
     }): Promise<APIResponse<CronJob>>;
     /**
      * Update a cron job.
+     * Uses PATCH per backend CronsController.
      */
     update(cronId: string, body: {
         schedule?: string;

package/dist/modules/crons.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crons.d.ts","sourceRoot":"","sources":["../../src/modules/crons.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAc,MAAM,kBAAkB,CAAC;AAK3E,MAAM,WAAW,OAAO;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAChC,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,WAAW;IACR,OAAO,CAAC,MAAM;IAAa,OAAO,CAAC,OAAO;gBAAlC,MAAM,EAAE,SAAS,EAAU,OAAO,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAEpF;;OAEG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,WAAW,CAAC,mBAAmB,CAAC,CAAC;IAO7C;;OAEG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAOxD;;OAEG;IACG,MAAM,CAAC,IAAI,EAAE;QACf,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;KACrB,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAOjC;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE;QAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,KAAK,CAAC,EAAE,OAAO,CAAC;KACnB,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAQjC;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAOxD;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,mBAAmB,CAAC,CAAC;CAM3E"}
+{"version":3,"file":"crons.d.ts","sourceRoot":"","sources":["../../src/modules/crons.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAc,MAAM,kBAAkB,CAAC;AAK3E,MAAM,WAAW,OAAO;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAChC,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,WAAW;IACR,OAAO,CAAC,MAAM;IAAa,OAAO,CAAC,OAAO;gBAAlC,MAAM,EAAE,SAAS,EAAU,OAAO,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAEpF;;OAEG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,WAAW,CAAC,mBAAmB,CAAC,CAAC;IAO7C;;OAEG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAOxD;;OAEG;IACG,MAAM,CAAC,IAAI,EAAE;QACf,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;KACrB,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAOjC;;;OAGG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE;QAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,KAAK,CAAC,EAAE,OAAO,CAAC;KACnB,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAQjC;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAOxD;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,mBAAmB,CAAC,CAAC;CAM3E"}

package/dist/modules/crons.js

@@ -37,9 +37,10 @@ export class CronsModule {
     }
     /**
      * Update a cron job.
+     * Uses PATCH per backend CronsController.
      */
     async update(cronId, body) {
-        return this.client.PUT("/v1/api/crons/{id}", {
+        return this.client.PATCH("/v1/api/crons/{id}", {
             params: { path: { id: cronId } },
             body,
             headers: this.headers(),

package/dist/modules/triggers.d.ts

@@ -106,6 +106,15 @@ export declare class TriggersModule {
     getSecret(triggerId: string): Promise<APIResponse<TriggerSecretResponse>>;
     /**
      * Create a new trigger.
+     * @example
+     * ```ts
+     * const { data: trigger } = await client.triggers.create({
+     *   name: "My Webhook",
+     *   agent_id: "agent-uuid",
+     *   trigger_type: "webhook",
+     *   idempotency_key: "create-trigger-unique-key"
+     * });
+     * ```
      */
     create(body: {
         name: string;
@@ -113,6 +122,8 @@ export declare class TriggersModule {
         trigger_type: string;
         template_slug?: string;
         config?: Record<string, unknown>;
+        /** Idempotency key for safe retries. When set, duplicate requests with the same key return 409 Conflict. */
+        idempotency_key?: string;
     }): Promise<APIResponse<Trigger>>;
     /**
      * Update a trigger.

package/dist/modules/triggers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"triggers.d.ts","sourceRoot":"","sources":["../../src/modules/triggers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAM/D,MAAM,WAAW,OAAO;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAE7B;AAED,MAAM,WAAW,sBAAsB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,EAAE,eAAe,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAC1C,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAChC,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACjB;AAMD,MAAM,WAAW,4BAA4B;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iBAAiB,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,sBAAsB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAChC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,uBAAuB,EAAE,OAAO,CAAC;IACjC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iBAAiB,CAAC,EAAE,sBAAsB,EAAE,CAAC;CAChD;AAMD,qBAAa,cAAc;IACX,OAAO,CAAC,MAAM;IAAa,OAAO,CAAC,OAAO;gBAAlC,MAAM,EAAE,SAAS,EAAU,OAAO,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAEpF;;OAEG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,WAAW,CAAC,mBAAmB,CAAC,CAAC;IAO7C;;;OAGG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,mBAAmB,CAAC,CAAC;IAI7E;;OAEG;IACG,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAO3D;;;OAGG;IACG,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,qBAAqB,CAAC,CAAC;IAO/E;;OAEG;IACG,MAAM,CAAC,IAAI,EAAE;QACf,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAOjC;;OAEG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE;QAClC,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,OAAO,CAAC;KACvB,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAQjC;;OAEG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAO3D;;;;;;;OAOG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,mBAAmB,CAAC,CAAC;IAYxI;;;OAGG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,4BAA4B,CAAC,CAAC;IAOxF;;;;;OAKG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,mBAAmB,CAAC,CAAC;CAO1G"}
+{"version":3,"file":"triggers.d.ts","sourceRoot":"","sources":["../../src/modules/triggers.ts"],"names":[],"mappings":"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"}

package/dist/modules/triggers.js

@@ -51,11 +51,26 @@ export class TriggersModule {
     }
     /**
      * Create a new trigger.
+     * @example
+     * ```ts
+     * const { data: trigger } = await client.triggers.create({
+     *   name: "My Webhook",
+     *   agent_id: "agent-uuid",
+     *   trigger_type: "webhook",
+     *   idempotency_key: "create-trigger-unique-key"
+     * });
+     * ```
      */
     async create(body) {
+        const headers = { ...this.headers() };
+        if (body.idempotency_key) {
+            headers["X-Idempotency-Key"] = body.idempotency_key;
+        }
+        // Send body without idempotency_key (it's header-only)
+        const { idempotency_key, ...requestBody } = body;
         return this.client.POST("/v1/api/triggers", {
-            body,
-            headers: this.headers(),
+            body: requestBody,
+            headers,
         });
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@agent-os-sdk/client",
-    "version": "0.7.11",
+    "version": "0.7.13",
     "description": "Official TypeScript SDK for Agent OS platform",
     "type": "module",
     "main": "./dist/index.js",
@@ -40,6 +40,7 @@
         "openapi-fetch": "^0.13.0"
     },
     "devDependencies": {
+        "@types/node": "^25.2.1",
         "openapi-typescript": "^7.4.0",
         "tsx": "^4.19.0",
         "typescript": "^5.5.0",
@@ -49,4 +50,4 @@
         "dist",
         "src"
     ]
-}
+}

package/src/client/HttpRequestBuilder.ts

@@ -0,0 +1,102 @@
+/**
+ * HttpRequestBuilder — Single source of truth for headers
+ * 
+ * All header generation flows through this builder.
+ * raw.ts should NOT generate headers directly.
+ * 
+ * Headers generated:
+ * - X-Request-Id: Per-request, always new (crypto.randomUUID)
+ * - X-Correlation-Id: Per-flow, immutable within flow
+ * - Authorization: Bearer token
+ * - X-Workspace-Id: Workspace binding (from context)
+ * - X-Idempotency-Key: Opt-in for POST requests
+ * - User-Agent: SDK version + runtime info
+ * 
+ * @see sdk-upgrade.md Section 1.3
+ */
+
+import type { OperationContext } from "./OperationContext.js";
+import { sanitizeHeader, sanitizeHeaders } from "./sanitize.js";
+
+// SDK version injected at build time, fallback for local dev
+declare const __SDK_VERSION__: string | undefined;
+const SDK_VERSION = typeof __SDK_VERSION__ !== "undefined" ? __SDK_VERSION__ : "0.7.12-dev";
+
+/**
+ * Options for building request headers
+ */
+export interface HttpRequestBuilderOptions {
+    /** Bearer token for Authorization header */
+    token?: string;
+    /** Operation context with correlationId and workspaceId */
+    context?: OperationContext;
+    /** Idempotency key for POST requests */
+    idempotencyKey?: string;
+    /** If true, throws if correlationId is missing */
+    requireFlow?: boolean;
+}
+
+/**
+ * Build headers for HTTP requests.
+ * This is the SINGLE SOURCE OF TRUTH for header generation.
+ */
+export class HttpRequestBuilder {
+    /**
+     * Build headers from options.
+     * 
+     * @throws Error if requireFlow is true and correlationId is missing
+     */
+    build(opts: HttpRequestBuilderOptions): Record<string, string> {
+        const headers: Record<string, string> = {};
+
+        // I2: X-Request-Id always exists (per request)
+        headers["X-Request-Id"] = crypto.randomUUID();
+
+        // User-Agent: Dynamic SDK version
+        headers["User-Agent"] = this.buildUserAgent();
+
+        // I3: X-Correlation-Id is per flow
+        if (opts.requireFlow && !opts.context?.correlationId) {
+            throw new Error("X-Correlation-Id required for flow-scoped operations");
+        }
+        if (opts.context?.correlationId) {
+            headers["X-Correlation-Id"] = opts.context.correlationId;
+        }
+
+        // Authorization
+        if (opts.token) {
+            headers["Authorization"] = `Bearer ${opts.token}`;
+        }
+
+        // X-Workspace-Id from context
+        if (opts.context?.workspaceId) {
+            headers["X-Workspace-Id"] = opts.context.workspaceId;
+        }
+
+        // I7: Idempotency is opt-in
+        if (opts.idempotencyKey) {
+            headers["X-Idempotency-Key"] = sanitizeHeader(opts.idempotencyKey);
+        }
+
+        return sanitizeHeaders(headers);
+    }
+
+    /**
+     * Build User-Agent string with SDK version and runtime info
+     */
+    private buildUserAgent(): string {
+        // Node.js environment
+        if (typeof process !== "undefined" && process.version) {
+            return `agent-os-sdk/${SDK_VERSION} (node/${process.version})`;
+        }
+        // Browser environment
+        if (typeof navigator !== "undefined" && navigator.userAgent) {
+            return `agent-os-sdk/${SDK_VERSION} (browser)`;
+        }
+        // Unknown environment
+        return `agent-os-sdk/${SDK_VERSION}`;
+    }
+}
+
+// Singleton instance for convenience
+export const httpRequestBuilder = new HttpRequestBuilder();

package/src/client/OperationContext.ts

@@ -0,0 +1,22 @@
+/**
+ * OperationContext — Immutable flow context
+ * 
+ * Created at the start of a logical flow and never mutates.
+ * 
+ * - correlationId: Tracks the entire logical operation (immutable per flow)
+ * - workspaceId: Optional workspace binding
+ * 
+ * @see sdk-upgrade.md Section 1.1
+ */
+
+export type OperationContext = Readonly<{
+    correlationId: string;
+    workspaceId?: string;
+}>;
+
+export function createOperationContext(input: {
+    correlationId: string;
+    workspaceId?: string;
+}): OperationContext {
+    return Object.freeze({ ...input });
+}

package/src/client/OperationContextProvider.ts

@@ -0,0 +1,89 @@
+/**
+ * OperationContextProvider — Flow lifecycle management
+ * 
+ * Provider defines the lifecycle of a flow context.
+ * Implementations can use AsyncLocalStorage or manual context passing.
+ * 
+ * @see sdk-upgrade.md Section 1.2
+ */
+
+import type { OperationContext } from "./OperationContext.js";
+
+/**
+ * Interface for context providers
+ */
+export interface OperationContextProvider {
+    get(): OperationContext | undefined;
+}
+
+/**
+ * Default provider that always returns undefined.
+ * Used when no flow context is established.
+ */
+export class DefaultContextProvider implements OperationContextProvider {
+    get(): OperationContext | undefined {
+        return undefined;
+    }
+}
+
+/**
+ * AsyncLocalStorage-based provider for Node.js environments.
+ * Automatically propagates context through async call chains.
+ * 
+ * Note: This class requires Node.js async_hooks module.
+ * Import and use only in Node.js environments.
+ */
+export class AsyncLocalStorageContextProvider implements OperationContextProvider {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    private readonly storage: any;
+
+    constructor() {
+        // Dynamic import to avoid browser errors
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const asyncHooks = require("async_hooks");
+            this.storage = new asyncHooks.AsyncLocalStorage();
+        } catch {
+            throw new Error("AsyncLocalStorage requires Node.js environment");
+        }
+    }
+
+    get(): OperationContext | undefined {
+        return this.storage?.getStore();
+    }
+
+    /**
+     * Run a function within a context.
+     * The context is automatically available to all async operations within.
+     */
+    run<T>(context: OperationContext, fn: () => T): T {
+        return this.storage.run(context, fn);
+    }
+
+    /**
+     * Run an async function within a context.
+     */
+    runAsync<T>(context: OperationContext, fn: () => Promise<T>): Promise<T> {
+        return this.storage.run(context, fn);
+    }
+}
+
+/**
+ * Manual provider for environments without AsyncLocalStorage.
+ * Context must be explicitly set and cleared.
+ */
+export class ManualContextProvider implements OperationContextProvider {
+    private context: OperationContext | undefined;
+
+    get(): OperationContext | undefined {
+        return this.context;
+    }
+
+    set(context: OperationContext): void {
+        this.context = context;
+    }
+
+    clear(): void {
+        this.context = undefined;
+    }
+}

package/src/client/raw.ts

@@ -7,6 +7,8 @@
 
 import createClient, { type Client } from "openapi-fetch";
 import type { components, paths } from "../generated/openapi.js";
+import { httpRequestBuilder } from "./HttpRequestBuilder.js";
+import type { OperationContext } from "./OperationContext.js";
 
 // Re-export types for external use
 export type { components, paths };
@@ -111,6 +113,12 @@ export function createRawClient(options: ClientOptions) {
             retry?: boolean;
             /** Override timeout for this request */
             timeoutMs?: number;
+            /** Operation context for flow tracing */
+            context?: OperationContext;
+            /** Idempotency key for POST requests */
+            idempotencyKey?: string;
+            /** Require correlation ID (throws if missing) */
+            requireFlow?: boolean;
         }
     ): Promise<APIResponse<T>> {
         // Replace path params
@@ -152,15 +160,18 @@ export function createRawClient(options: ClientOptions) {
             headers["Content-Type"] = "application/json";
         }
 
-        // Detect idempotency from header or body
-        const hasIdempotencyKey = Boolean(
-            headers["Idempotency-Key"] ||
-            headers["idempotency-key"] ||
-            (opts?.body && typeof opts.body === "object" && (opts.body as Record<string, unknown>).idempotency_key)
-        );
+        // Build standard headers via HttpRequestBuilder (single source of truth)
+        const builderHeaders = httpRequestBuilder.build({
+            context: opts?.context,
+            idempotencyKey: opts?.idempotencyKey,
+            requireFlow: opts?.requireFlow,
+        });
+
+        // Merge builder headers (X-Request-Id, X-Correlation-Id, X-Idempotency-Key, User-Agent)
+        Object.assign(headers, builderHeaders);
 
-        // Generate client request ID for tracing
-        const clientRequestId = `sdk_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+        // Use X-Request-Id from builder as client request ID
+        const clientRequestId = headers["X-Request-Id"];
 
         // Call onRequest hook
         const startTime = Date.now();
@@ -233,6 +244,8 @@ export function createRawClient(options: ClientOptions) {
                     code: errorBody?.code || `HTTP_${response.status}`,
                     message: errorBody?.message || response.statusText,
                     details: errorBody?.details,
+                    // Include full error body for 422 responses with hints
+                    ...errorBody,
                 },
                 response,
                 meta: { requestId },

package/src/client/sanitize.ts

@@ -0,0 +1,31 @@
+/**
+ * Header Sanitization — Security layer for HTTP headers
+ * 
+ * Removes control characters and enforces size limits.
+ * 
+ * @see sdk-upgrade.md Section 1.4
+ */
+
+const MAX_LEN = 1024;
+
+/**
+ * Sanitize a single header value.
+ * - Removes control characters (0x00-0x1F, 0x7F)
+ * - Truncates to MAX_LEN
+ */
+export function sanitizeHeader(v: string): string {
+    return v.replace(/[\u0000-\u001F\u007F]/g, "").slice(0, MAX_LEN);
+}
+
+/**
+ * Sanitize all header values in a record.
+ * Mutates in place for performance.
+ */
+export function sanitizeHeaders(h: Record<string, string>): Record<string, string> {
+    for (const k in h) {
+        if (Object.prototype.hasOwnProperty.call(h, k) && h[k] !== undefined) {
+            h[k] = sanitizeHeader(h[k]);
+        }
+    }
+    return h;
+}

package/src/index.ts

@@ -63,6 +63,21 @@ export {
     isRetryableError,
 } from "./errors/index.js";
 
+// ============================================================
+// Auth Hardening (Pedra Sólida)
+// ============================================================
+
+export type { OperationContext } from "./client/OperationContext.js";
+export { createOperationContext } from "./client/OperationContext.js";
+export type { OperationContextProvider } from "./client/OperationContextProvider.js";
+export {
+    DefaultContextProvider,
+    AsyncLocalStorageContextProvider,
+    ManualContextProvider,
+} from "./client/OperationContextProvider.js";
+export { HttpRequestBuilder, httpRequestBuilder } from "./client/HttpRequestBuilder.js";
+export { sanitizeHeader, sanitizeHeaders } from "./client/sanitize.js";
+
 // ============================================================
 // Utilities
 // ============================================================