@caracalai/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2026] [Garudex Labs]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/advanced.d.ts

@@ -0,0 +1,8 @@
+export * from "./envelope.js";
+export * from "./context.js";
+export * from "./coordinator.js";
+export * from "./primitives.js";
+export * from "./http.js";
+export { Caracal } from "./client.js";
+export type { CaracalConfig, SpawnOptions, DelegateOptions, LifecycleHook } from "./client.js";
+//# sourceMappingURL=advanced.d.ts.map

package/dist/advanced.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":"AAUA,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/advanced.js

@@ -0,0 +1,16 @@
+/*
+ * Copyright (C) 2026 Garudex Labs.  All Rights Reserved.
+ * Caracal, a product of Garudex Labs
+ *
+ * Advanced surface: low-level primitives, codec, ambient context plumbing,
+ * and the raw coordinator client. Most integrators only need the default
+ * "@caracalai/sdk" entrypoint; reach for these when building a transport
+ * adapter or a framework shim.
+ */
+export * from "./envelope.js";
+export * from "./context.js";
+export * from "./coordinator.js";
+export * from "./primitives.js";
+export * from "./http.js";
+export { Caracal } from "./client.js";
+//# sourceMappingURL=advanced.js.map

package/dist/advanced.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced.js","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,61 @@
+import { type CaracalContext } from "./context.js";
+import { type HeaderGetter } from "./envelope.js";
+import { type CoordinatorClient } from "./coordinator.js";
+import { AgentKind, type DelegationConstraints } from "./coordinator.js";
+export interface ResourceBinding {
+    resourceId: string;
+    upstreamPrefix: string;
+}
+export interface CaracalConfig {
+    coordinator: CoordinatorClient;
+    zoneId: string;
+    applicationId: string;
+    subjectToken: string;
+    gatewayUrl?: string;
+    resources?: ResourceBinding[];
+    defaultKind?: AgentKind;
+    defaultTtlSeconds?: number;
+}
+export interface SpawnOptions {
+    kind?: AgentKind;
+    ttlSeconds?: number;
+    sessionSid?: string;
+    parentId?: string;
+    metadata?: Record<string, unknown>;
+    traceId?: string;
+}
+export interface DelegateOptions {
+    to: string;
+    toApplicationId: string;
+    scopes: string[];
+    constraints?: DelegationConstraints;
+    ttlSeconds?: number;
+}
+export type LifecycleHook = (ctx: CaracalContext) => void | Promise<void>;
+export declare class Caracal {
+    readonly config: CaracalConfig;
+    private agentStartHooks;
+    private agentEndHooks;
+    constructor(config: CaracalConfig);
+    static fromEnv(env?: NodeJS.ProcessEnv): Caracal;
+    spawn<T>(fn: () => Promise<T>, opts?: SpawnOptions): Promise<T>;
+    delegate<T>(opts: DelegateOptions, fn: () => Promise<T>): Promise<T>;
+    onAgentStart(cb: LifecycleHook): void;
+    onAgentEnd(cb: LifecycleHook): void;
+    private fire;
+    current(): CaracalContext | undefined;
+    headers(): Record<string, string>;
+    bindFromHeaders<T>(headers: Record<string, string | string[] | undefined> | HeaderGetter, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Returns a fetch-shaped function that injects the Caracal envelope (traceparent
+     * + baggage) onto outbound requests and, for gateway-routed calls, replaces the
+     * `Authorization` header with the current subject token. Pass to any provider
+     * SDK that accepts a custom fetch.
+     */
+    transport(): typeof fetch;
+    private routeThroughGateway;
+    middleware(): (req: {
+        headers: Record<string, string | string[] | undefined>;
+    }, _res: unknown, next: (err?: unknown) => void) => void;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -0,0 +1,233 @@
+/*
+ * Copyright (C) 2026 Garudex Labs.  All Rights Reserved.
+ * Caracal, a product of Garudex Labs
+ *
+ * Caracal: drop-in bound client wrapping zone, application, subject token, and coordinator.
+ */
+import { bind, fromEnvelope, toEnvelope, current } from "./context.js";
+import { decodeEnvelope, toHeaders, } from "./envelope.js";
+import { spawn as spawnPrimitive, delegate as delegatePrimitive, } from "./primitives.js";
+import { AgentKind } from "./coordinator.js";
+export class Caracal {
+    config;
+    agentStartHooks = [];
+    agentEndHooks = [];
+    constructor(config) {
+        this.config = config;
+    }
+    static fromEnv(env = process.env) {
+        const url = env.CARACAL_COORDINATOR_URL;
+        const zoneId = env.CARACAL_ZONE_ID;
+        const applicationId = env.CARACAL_APPLICATION_ID;
+        const subjectToken = env.CARACAL_SUBJECT_TOKEN;
+        const gatewayUrl = env.CARACAL_GATEWAY_URL;
+        const missing = [
+            ["CARACAL_COORDINATOR_URL", url],
+            ["CARACAL_ZONE_ID", zoneId],
+            ["CARACAL_APPLICATION_ID", applicationId],
+            ["CARACAL_SUBJECT_TOKEN", subjectToken],
+        ].filter(([, v]) => !v).map(([k]) => k);
+        if (missing.length) {
+            throw new Error(`Caracal.fromEnv: missing ${missing.join(", ")}`);
+        }
+        return new Caracal({
+            coordinator: { baseUrl: url },
+            zoneId: zoneId,
+            applicationId: applicationId,
+            subjectToken: subjectToken,
+            gatewayUrl,
+            resources: parseResourceBindings(env.CARACAL_RESOURCES),
+        });
+    }
+    spawn(fn, opts = {}) {
+        const input = {
+            coordinator: this.config.coordinator,
+            zoneId: this.config.zoneId,
+            applicationId: this.config.applicationId,
+            subjectToken: this.config.subjectToken,
+            kind: opts.kind ?? this.config.defaultKind ?? AgentKind.Instance,
+            ttlSeconds: opts.ttlSeconds ?? this.config.defaultTtlSeconds,
+            sessionSid: opts.sessionSid,
+            parentId: opts.parentId,
+            metadata: opts.metadata,
+            traceId: opts.traceId,
+            onAgentStart: this.agentStartHooks.length ? (c) => this.fire(this.agentStartHooks, c) : undefined,
+            onAgentEnd: this.agentEndHooks.length ? (c) => this.fire(this.agentEndHooks, c) : undefined,
+        };
+        return spawnPrimitive(input, fn);
+    }
+    delegate(opts, fn) {
+        const input = {
+            coordinator: this.config.coordinator,
+            toAgentSessionId: opts.to,
+            toApplicationId: opts.toApplicationId,
+            scopes: opts.scopes,
+            constraints: opts.constraints,
+            ttlSeconds: opts.ttlSeconds,
+        };
+        return delegatePrimitive(input, fn);
+    }
+    onAgentStart(cb) {
+        this.agentStartHooks.push(cb);
+    }
+    onAgentEnd(cb) {
+        this.agentEndHooks.push(cb);
+    }
+    async fire(hooks, ctx) {
+        for (const h of hooks)
+            await h(ctx);
+    }
+    current() {
+        return current();
+    }
+    headers() {
+        const ctx = current();
+        if (!ctx) {
+            return toHeaders({
+                subjectToken: this.config.subjectToken,
+                hop: 0,
+            });
+        }
+        return toHeaders(toEnvelope(ctx));
+    }
+    bindFromHeaders(headers, fn) {
+        const env = typeof headers === "function"
+            ? decodeEnvelope(headers)
+            : decodeEnvelope((n) => {
+                const lower = n.toLowerCase();
+                for (const k of Object.keys(headers)) {
+                    if (k.toLowerCase() === lower) {
+                        const v = headers[k];
+                        return Array.isArray(v) ? v[0] : v;
+                    }
+                }
+                return undefined;
+            });
+        if (!env.subjectToken)
+            env.subjectToken = this.config.subjectToken;
+        const ctx = fromEnvelope(env, {
+            zoneId: this.config.zoneId,
+            clientId: this.config.applicationId,
+        });
+        return bind(ctx, fn);
+    }
+    /**
+     * Returns a fetch-shaped function that injects the Caracal envelope (traceparent
+     * + baggage) onto outbound requests and, for gateway-routed calls, replaces the
+     * `Authorization` header with the current subject token. Pass to any provider
+     * SDK that accepts a custom fetch.
+     */
+    transport() {
+        const outer = this;
+        const fn = (async (input, init) => {
+            const ctx = current();
+            const env = ctx
+                ? toEnvelope(ctx)
+                : { subjectToken: outer.config.subjectToken, hop: 0 };
+            const merged = new Headers(init?.headers ?? {});
+            for (const [k, v] of Object.entries(toHeaders(env))) {
+                if (!merged.has(k))
+                    merged.set(k, v);
+            }
+            const fetchImpl = outer.config.coordinator.fetchImpl ?? fetch;
+            const explicitResource = merged.get("X-Caracal-Resource") ?? undefined;
+            const rewritten = outer.routeThroughGateway(input, explicitResource);
+            if (rewritten) {
+                merged.set("X-Caracal-Resource", rewritten.resourceId);
+                merged.set("Authorization", `Bearer ${env.subjectToken ?? outer.config.subjectToken}`);
+                return fetchImpl(rewritten.url, { ...init, headers: merged });
+            }
+            return fetchImpl(input, { ...init, headers: merged });
+        });
+        return fn;
+    }
+    routeThroughGateway(input, explicitResource) {
+        const gw = this.config.gatewayUrl;
+        if (!gw)
+            return null;
+        const raw = typeof input === "string"
+            ? input
+            : input instanceof URL
+                ? input.toString()
+                : input.url;
+        let parsed;
+        try {
+            parsed = new URL(raw);
+        }
+        catch {
+            return null;
+        }
+        if (sameOrigin(parsed, gw))
+            return null;
+        const binding = explicitResource
+            ? this.config.resources?.find((b) => b.resourceId === explicitResource)
+            : this.config.resources?.find((b) => urlMatchesPrefix(parsed, b.upstreamPrefix));
+        if (!binding && !explicitResource)
+            return null;
+        const gateway = new URL(gw);
+        let suffix = parsed.pathname + parsed.search;
+        if (binding) {
+            const prefix = new URL(binding.upstreamPrefix);
+            if (parsed.pathname.startsWith(prefix.pathname) && prefix.pathname !== "/") {
+                suffix = parsed.pathname.slice(prefix.pathname.length) + parsed.search;
+                if (!suffix.startsWith("/"))
+                    suffix = "/" + suffix;
+            }
+        }
+        const base = gateway.origin + gateway.pathname.replace(/\/$/, "");
+        const target = base + suffix;
+        return { url: target, resourceId: binding?.resourceId ?? explicitResource };
+    }
+    middleware() {
+        return (req, _res, next) => {
+            this.bindFromHeaders(req.headers, async () => {
+                next();
+            }).catch(next);
+        };
+    }
+}
+function sameOrigin(a, b) {
+    try {
+        const o = new URL(b);
+        return a.protocol === o.protocol && a.host === o.host;
+    }
+    catch {
+        return false;
+    }
+}
+function urlMatchesPrefix(target, prefix) {
+    let p;
+    try {
+        p = new URL(prefix);
+    }
+    catch {
+        return false;
+    }
+    if (p.protocol !== target.protocol)
+        return false;
+    if (p.host !== target.host)
+        return false;
+    if (p.pathname === "/" || p.pathname === "")
+        return true;
+    return target.pathname === p.pathname || target.pathname.startsWith(p.pathname.endsWith("/") ? p.pathname : p.pathname + "/");
+}
+function parseResourceBindings(raw) {
+    if (!raw)
+        return undefined;
+    const out = [];
+    for (const entry of raw.split(",")) {
+        const trimmed = entry.trim();
+        if (!trimmed)
+            continue;
+        const idx = trimmed.indexOf("=");
+        if (idx <= 0)
+            continue;
+        const resourceId = trimmed.slice(0, idx).trim();
+        const upstreamPrefix = trimmed.slice(idx + 1).trim();
+        if (resourceId && upstreamPrefix) {
+            out.push({ resourceId, upstreamPrefix });
+        }
+    }
+    return out.length ? out : undefined;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/context.d.ts

@@ -0,0 +1,21 @@
+import { Envelope } from "./envelope.js";
+export interface CaracalContext {
+    subjectToken: string;
+    zoneId: string;
+    clientId: string;
+    agentSessionId?: string;
+    delegationEdgeId?: string;
+    parentEdgeId?: string;
+    sessionId?: string;
+    traceId?: string;
+    hop: number;
+}
+export declare function current(): CaracalContext | undefined;
+export declare function bind<T>(ctx: CaracalContext, fn: () => T | Promise<T>): T | Promise<T>;
+export declare function withOverrides<T>(patch: Partial<CaracalContext>, fn: () => T | Promise<T>): T | Promise<T>;
+export declare function toEnvelope(ctx: CaracalContext): Envelope;
+export declare function fromEnvelope(env: Envelope, base: {
+    zoneId: string;
+    clientId: string;
+}): CaracalContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAID,wBAAgB,OAAO,IAAI,cAAc,GAAG,SAAS,CAEpD;AAED,wBAAgB,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAErF;AAED,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,OAAO,CAAC,cAAc,CAAC,EAC9B,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAIhB;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,cAAc,GAAG,QAAQ,CASxD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAYtG"}

package/dist/context.js

@@ -0,0 +1,45 @@
+/*
+ * Copyright (C) 2026 Garudex Labs.  All Rights Reserved.
+ * Caracal, a product of Garudex Labs
+ *
+ * CaracalContext: ambient identity and delegation context propagated across async boundaries.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+export function current() {
+    return storage.getStore();
+}
+export function bind(ctx, fn) {
+    return storage.run(ctx, fn);
+}
+export function withOverrides(patch, fn) {
+    const base = current();
+    if (!base)
+        throw new Error("withOverrides requires an existing Caracal context");
+    return storage.run({ ...base, ...patch }, fn);
+}
+export function toEnvelope(ctx) {
+    return {
+        subjectToken: ctx.subjectToken,
+        agentSessionId: ctx.agentSessionId,
+        delegationEdgeId: ctx.delegationEdgeId,
+        parentEdgeId: ctx.parentEdgeId,
+        traceId: ctx.traceId,
+        hop: ctx.hop,
+    };
+}
+export function fromEnvelope(env, base) {
+    if (!env.subjectToken)
+        throw new Error("envelope missing subject token");
+    return {
+        subjectToken: env.subjectToken,
+        zoneId: base.zoneId,
+        clientId: base.clientId,
+        agentSessionId: env.agentSessionId,
+        delegationEdgeId: env.delegationEdgeId,
+        parentEdgeId: env.parentEdgeId,
+        traceId: env.traceId,
+        hop: env.hop,
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAerD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAkB,CAAC;AAExD,MAAM,UAAU,OAAO;IACrB,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,IAAI,CAAI,GAAmB,EAAE,EAAwB;IACnE,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,KAA8B,EAC9B,EAAwB;IAExB,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACjF,OAAO,OAAO,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAmB;IAC5C,OAAO;QACL,YAAY,EAAE,GAAG,CAAC,YAAY;QAC9B,cAAc,EAAE,GAAG,CAAC,cAAc;QAClC,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;QACtC,YAAY,EAAE,GAAG,CAAC,YAAY;QAC9B,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,GAAG,EAAE,GAAG,CAAC,GAAG;KACb,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAa,EAAE,IAA0C;IACpF,IAAI,CAAC,GAAG,CAAC,YAAY;QAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACzE,OAAO;QACL,YAAY,EAAE,GAAG,CAAC,YAAY;QAC9B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,cAAc,EAAE,GAAG,CAAC,cAAc;QAClC,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;QACtC,YAAY,EAAE,GAAG,CAAC,YAAY;QAC9B,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,GAAG,EAAE,GAAG,CAAC,GAAG;KACb,CAAC;AACJ,CAAC"}

package/dist/coordinator.d.ts

@@ -0,0 +1,47 @@
+export interface CoordinatorClient {
+    baseUrl: string;
+    fetchImpl?: typeof fetch;
+}
+export declare const AgentKind: {
+    readonly Service: "service";
+    readonly Instance: "instance";
+    readonly Ephemeral: "ephemeral";
+};
+export type AgentKind = typeof AgentKind[keyof typeof AgentKind];
+export interface DelegationConstraints {
+    resources?: string[];
+    actions?: string[];
+    maxDepth?: number;
+    expiresAt?: string;
+}
+export interface SpawnRequest {
+    zoneId: string;
+    applicationId: string;
+    sessionSid?: string;
+    parentId?: string;
+    kind?: AgentKind;
+    ttlSeconds?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface SpawnResponse {
+    id?: string;
+    agent_session_id: string;
+}
+export interface DelegationRequest {
+    zoneId: string;
+    issuerApplicationId: string;
+    sourceSessionId: string;
+    targetSessionId: string;
+    receiverApplicationId: string;
+    scopes: string[];
+    constraints?: DelegationConstraints;
+    ttlSeconds?: number;
+}
+export interface DelegationResponse {
+    id?: string;
+    delegation_edge_id: string;
+}
+export declare function spawnAgent(client: CoordinatorClient, bearer: string, req: SpawnRequest): Promise<SpawnResponse>;
+export declare function terminateAgent(client: CoordinatorClient, bearer: string, zoneId: string, agentSessionId: string): Promise<void>;
+export declare function createDelegation(client: CoordinatorClient, bearer: string, req: DelegationRequest): Promise<DelegationResponse>;
+//# sourceMappingURL=coordinator.d.ts.map

package/dist/coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../src/coordinator.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,eAAO,MAAM,SAAS;;;;CAIZ,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAEjE,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAyBD,wBAAsB,UAAU,CAC9B,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,YAAY,GAChB,OAAO,CAAC,aAAa,CAAC,CAWxB;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CASf;AAED,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,kBAAkB,CAAC,CAoB7B"}

package/dist/coordinator.js

@@ -0,0 +1,70 @@
+/*
+ * Copyright (C) 2026 Garudex Labs.  All Rights Reserved.
+ * Caracal, a product of Garudex Labs
+ *
+ * Coordinator REST client used by SDK primitives.
+ */
+export const AgentKind = {
+    Service: "service",
+    Instance: "instance",
+    Ephemeral: "ephemeral",
+};
+async function call(client, method, path, bearer, body) {
+    const fetchFn = client.fetchImpl ?? fetch;
+    const res = await fetchFn(`${client.baseUrl}${path}`, {
+        method,
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${bearer}`,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`coordinator ${method} ${path} failed: ${res.status} ${text}`);
+    }
+    return (await res.json());
+}
+export async function spawnAgent(client, bearer, req) {
+    const res = await call(client, "POST", `/zones/${encodeURIComponent(req.zoneId)}/agents`, bearer, {
+        application_id: req.applicationId,
+        session_sid: req.sessionSid,
+        parent_id: req.parentId,
+        kind: req.kind ?? AgentKind.Instance,
+        ttl_seconds: req.ttlSeconds,
+        metadata: req.metadata,
+    });
+    if (!res.agent_session_id && res.id)
+        res.agent_session_id = res.id;
+    return res;
+}
+export async function terminateAgent(client, bearer, zoneId, agentSessionId) {
+    const fetchFn = client.fetchImpl ?? fetch;
+    await fetchFn(`${client.baseUrl}/zones/${encodeURIComponent(zoneId)}/agents/${encodeURIComponent(agentSessionId)}`, {
+        method: "DELETE",
+        headers: { authorization: `Bearer ${bearer}` },
+    }).catch(() => undefined);
+}
+export async function createDelegation(client, bearer, req) {
+    const constraints = req.constraints
+        ? {
+            resources: req.constraints.resources,
+            actions: req.constraints.actions,
+            max_depth: req.constraints.maxDepth,
+            expires_at: req.constraints.expiresAt,
+        }
+        : undefined;
+    const res = await call(client, "POST", `/zones/${encodeURIComponent(req.zoneId)}/delegations`, bearer, {
+        issuer_application_id: req.issuerApplicationId,
+        source_session_id: req.sourceSessionId,
+        target_session_id: req.targetSessionId,
+        receiver_application_id: req.receiverApplicationId,
+        scopes: req.scopes,
+        constraints,
+        ttl_seconds: req.ttlSeconds,
+    });
+    if (!res.delegation_edge_id && res.id)
+        res.delegation_edge_id = res.id;
+    return res;
+}
+//# sourceMappingURL=coordinator.js.map

package/dist/coordinator.js.map

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

package/dist/envelope.d.ts

@@ -0,0 +1,31 @@
+export declare const HeaderAuthorization = "authorization";
+export declare const HeaderTraceparent = "traceparent";
+export declare const HeaderBaggage = "baggage";
+export declare const BaggageAgentSession = "caracal.agent_session";
+export declare const BaggageDelegationEdge = "caracal.delegation_edge";
+export declare const BaggageParentEdge = "caracal.parent_edge";
+export declare const BaggageHop = "caracal.hop";
+export declare const MaxHop = 32;
+export interface Envelope {
+    subjectToken?: string;
+    agentSessionId?: string;
+    delegationEdgeId?: string;
+    parentEdgeId?: string;
+    traceId?: string;
+    hop: number;
+}
+export type HeaderGetter = (name: string) => string | undefined;
+export type HeaderSetter = (name: string, value: string) => void;
+export declare function formatTraceparent(traceId: string): string;
+export declare function parseTraceparent(value: string): {
+    traceId: string;
+} | undefined;
+export declare function encodeBaggage(entries: Record<string, string | undefined>): string;
+export declare function parseBaggage(value: string | undefined): Record<string, string>;
+export declare function fromHeaders(headers: Record<string, string | string[] | undefined>): Envelope;
+export declare function decodeEnvelope(get: HeaderGetter): Envelope;
+export declare function encodeEnvelope(env: Envelope, set: HeaderSetter): void;
+export declare function toHeaders(env: Envelope): Record<string, string>;
+export declare function inject(env: Envelope, carrier: Record<string, string>): void;
+export declare function extract(carrier: Record<string, string | string[] | undefined>): Envelope;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,mBAAmB,kBAAkB,CAAC;AACnD,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAC/C,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAC3D,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAC/D,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AACvD,eAAO,MAAM,UAAU,gBAAgB,CAAC;AAExC,eAAO,MAAM,MAAM,KAAK,CAAC;AAEzB,MAAM,WAAW,QAAQ;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;AAChE,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;AAyBjE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAK/E;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,CAOjF;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgB9E;AAaD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,QAAQ,CAE5F;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,YAAY,GAAG,QAAQ,CAiB1D;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,YAAY,GAAG,IAAI,CAWrE;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM/D;AAED,wBAAgB,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAI3E;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,QAAQ,CAExF"}

package/dist/envelope.js

@@ -0,0 +1,140 @@
+/*
+ * Copyright (C) 2026 Garudex Labs.  All Rights Reserved.
+ * Caracal, a product of Garudex Labs
+ *
+ * Wire envelope using W3C Trace Context (traceparent) and W3C Baggage.
+ *
+ * Subject token rides in Authorization. Caracal-specific cross-cutting fields
+ * (agent_session, delegation_edge, parent_edge, hop) ride in Baggage under the
+ * caracal.* namespace. Trace identifiers ride in traceparent so any
+ * OpenTelemetry-aware client/server propagates them transparently.
+ */
+export const HeaderAuthorization = "authorization";
+export const HeaderTraceparent = "traceparent";
+export const HeaderBaggage = "baggage";
+export const BaggageAgentSession = "caracal.agent_session";
+export const BaggageDelegationEdge = "caracal.delegation_edge";
+export const BaggageParentEdge = "caracal.parent_edge";
+export const BaggageHop = "caracal.hop";
+export const MaxHop = 32;
+const TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+function randomHex(byteLen) {
+    const bytes = new Uint8Array(byteLen);
+    if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+        crypto.getRandomValues(bytes);
+    }
+    else {
+        for (let i = 0; i < byteLen; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    }
+    let s = "";
+    for (const b of bytes)
+        s += b.toString(16).padStart(2, "0");
+    return s;
+}
+function genTraceId() {
+    return randomHex(16);
+}
+function genSpanId() {
+    return randomHex(8);
+}
+export function formatTraceparent(traceId) {
+    return `00-${traceId}-${genSpanId()}-01`;
+}
+export function parseTraceparent(value) {
+    const m = TRACEPARENT_RE.exec(value.trim());
+    if (!m)
+        return undefined;
+    if (m[2] === "00000000000000000000000000000000")
+        return undefined;
+    return { traceId: m[2] };
+}
+export function encodeBaggage(entries) {
+    const parts = [];
+    for (const [k, v] of Object.entries(entries)) {
+        if (v === undefined || v === "")
+            continue;
+        parts.push(`${k}=${encodeURIComponent(v)}`);
+    }
+    return parts.join(",");
+}
+export function parseBaggage(value) {
+    const out = {};
+    if (!value)
+        return out;
+    for (const piece of value.split(",")) {
+        const eq = piece.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const k = piece.slice(0, eq).trim();
+        const semi = piece.indexOf(";", eq + 1);
+        const rawV = (semi === -1 ? piece.slice(eq + 1) : piece.slice(eq + 1, semi)).trim();
+        try {
+            out[k] = decodeURIComponent(rawV);
+        }
+        catch {
+            out[k] = rawV;
+        }
+    }
+    return out;
+}
+const headerKey = (h, name) => {
+    const lower = name.toLowerCase();
+    for (const k of Object.keys(h)) {
+        if (k.toLowerCase() === lower) {
+            const v = h[k];
+            return Array.isArray(v) ? v[0] : v;
+        }
+    }
+    return undefined;
+};
+export function fromHeaders(headers) {
+    return decodeEnvelope((n) => headerKey(headers, n));
+}
+export function decodeEnvelope(get) {
+    const auth = get(HeaderAuthorization);
+    const subjectToken = auth && /^Bearer\s+/i.test(auth) ? auth.replace(/^Bearer\s+/i, "").trim() : undefined;
+    const tp = get(HeaderTraceparent);
+    const traceId = tp ? parseTraceparent(tp)?.traceId : undefined;
+    const bag = parseBaggage(get(HeaderBaggage));
+    const hopRaw = bag[BaggageHop];
+    const hop = hopRaw ? Math.max(0, Math.min(MaxHop, parseInt(hopRaw, 10) || 0)) : 0;
+    return {
+        subjectToken,
+        agentSessionId: bag[BaggageAgentSession] || undefined,
+        delegationEdgeId: bag[BaggageDelegationEdge] || undefined,
+        parentEdgeId: bag[BaggageParentEdge] || undefined,
+        traceId,
+        hop,
+    };
+}
+export function encodeEnvelope(env, set) {
+    if (env.subjectToken)
+        set(HeaderAuthorization, `Bearer ${env.subjectToken}`);
+    const traceId = env.traceId && /^[0-9a-f]{32}$/.test(env.traceId) ? env.traceId : genTraceId();
+    set(HeaderTraceparent, formatTraceparent(traceId));
+    const baggage = encodeBaggage({
+        [BaggageAgentSession]: env.agentSessionId,
+        [BaggageDelegationEdge]: env.delegationEdgeId,
+        [BaggageParentEdge]: env.parentEdgeId,
+        [BaggageHop]: String(env.hop),
+    });
+    if (baggage)
+        set(HeaderBaggage, baggage);
+}
+export function toHeaders(env) {
+    const out = {};
+    encodeEnvelope(env, (n, v) => {
+        out[n] = v;
+    });
+    return out;
+}
+export function inject(env, carrier) {
+    encodeEnvelope(env, (n, v) => {
+        carrier[n] = v;
+    });
+}
+export function extract(carrier) {
+    return fromHeaders(carrier);
+}
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

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

package/dist/http.d.ts

@@ -0,0 +1,11 @@
+import { Caracal } from "./client.js";
+export interface IncomingLike {
+    headers: Record<string, string | string[] | undefined>;
+}
+export type ConnectMiddleware = (req: IncomingLike, res: unknown, next: (err?: unknown) => void) => void;
+export declare function caracalHttpMiddleware(caracal: Caracal): ConnectMiddleware;
+export interface FastifyRequestLike {
+    headers: Record<string, string | string[] | undefined>;
+}
+export declare function caracalFastifyHook(caracal: Caracal): (req: FastifyRequestLike) => Promise<void>;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEtC,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;CACxD;AAED,MAAM,MAAM,iBAAiB,GAAG,CAC9B,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,KAC1B,IAAI,CAAC;AAEV,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,iBAAiB,CAQzE;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;CACxD;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,IACnC,KAAK,kBAAkB,mBAGtC"}

package/dist/http.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright (C) 2026 Garudex Labs.  All Rights Reserved.
+ * Caracal, a product of Garudex Labs
+ *
+ * Generic HTTP server middleware: extracts the wire envelope from incoming requests
+ * and binds a CaracalContext for the handler scope. Works with Express, Connect,
+ * Fastify (via preHandler), and any framework exposing (req, res, next).
+ */
+export function caracalHttpMiddleware(caracal) {
+    return (req, _res, next) => {
+        caracal
+            .bindFromHeaders(req.headers, async () => {
+            next();
+        })
+            .catch(next);
+    };
+}
+export function caracalFastifyHook(caracal) {
+    return async (req) => {
+        await caracal.bindFromHeaders(req.headers, async () => undefined);
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAcH,MAAM,UAAU,qBAAqB,CAAC,OAAgB;IACpD,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QACzB,OAAO;aACJ,eAAe,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;YACvC,IAAI,EAAE,CAAC;QACT,CAAC,CAAC;aACD,KAAK,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC,CAAC;AACJ,CAAC;AAMD,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,OAAO,KAAK,EAAE,GAAuB,EAAE,EAAE;QACvC,MAAM,OAAO,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,SAAS,CAAC,CAAC;IACpE,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { Caracal } from "./client.js";
+export type { CaracalConfig, SpawnOptions, DelegateOptions, ResourceBinding, LifecycleHook } from "./client.js";
+export type { CaracalContext } from "./context.js";
+export type { CoordinatorClient } from "./coordinator.js";
+export { AgentKind } from "./coordinator.js";
+export type { DelegationConstraints } from "./coordinator.js";
+export type { Envelope } from "./envelope.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAChH,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/*
+ * Copyright (C) 2026 Garudex Labs.  All Rights Reserved.
+ * Caracal, a product of Garudex Labs
+ *
+ * Public surface of the Caracal SDK.
+ */
+export { Caracal } from "./client.js";
+export { AgentKind } from "./coordinator.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAItC,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/primitives.d.ts

@@ -0,0 +1,27 @@
+import { CaracalContext } from "./context.js";
+import { CoordinatorClient, AgentKind, DelegationConstraints } from "./coordinator.js";
+export interface SpawnInput {
+    coordinator: CoordinatorClient;
+    zoneId: string;
+    applicationId: string;
+    subjectToken: string;
+    sessionSid?: string;
+    parentId?: string;
+    kind?: AgentKind;
+    ttlSeconds?: number;
+    metadata?: Record<string, unknown>;
+    traceId?: string;
+    onAgentStart?: (ctx: CaracalContext) => void | Promise<void>;
+    onAgentEnd?: (ctx: CaracalContext) => void | Promise<void>;
+}
+export declare function spawn<T>(input: SpawnInput, fn: () => Promise<T>): Promise<T>;
+export interface DelegateInput {
+    coordinator: CoordinatorClient;
+    toAgentSessionId: string;
+    toApplicationId: string;
+    scopes: string[];
+    constraints?: DelegationConstraints;
+    ttlSeconds?: number;
+}
+export declare function delegate<T>(input: DelegateInput, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=primitives.d.ts.map

package/dist/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../src/primitives.ts"],"names":[],"mappings":"AAOA,OAAO,EAAiB,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EACL,iBAAiB,EAIjB,SAAS,EACT,qBAAqB,EACtB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,wBAAsB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAiClF;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,iBAAiB,CAAC;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,KAAK,EAAE,aAAa,EACpB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAuBZ"}

package/dist/primitives.js

@@ -0,0 +1,71 @@
+/*
+ * Copyright (C) 2026 Garudex Labs.  All Rights Reserved.
+ * Caracal, a product of Garudex Labs
+ *
+ * SDK primitives: spawn an agent session and delegate authority.
+ */
+import { bind, current } from "./context.js";
+import { spawnAgent, terminateAgent, createDelegation, AgentKind, } from "./coordinator.js";
+export async function spawn(input, fn) {
+    const parent = current();
+    const parentId = input.parentId ?? parent?.agentSessionId;
+    const bearer = input.subjectToken;
+    const kind = input.kind ?? AgentKind.Instance;
+    const res = await spawnAgent(input.coordinator, bearer, {
+        zoneId: input.zoneId,
+        applicationId: input.applicationId,
+        sessionSid: input.sessionSid,
+        parentId,
+        kind,
+        ttlSeconds: input.ttlSeconds,
+        metadata: input.metadata,
+    });
+    const ctx = {
+        subjectToken: bearer,
+        zoneId: input.zoneId,
+        clientId: input.applicationId,
+        agentSessionId: res.agent_session_id,
+        parentEdgeId: parent?.delegationEdgeId,
+        sessionId: input.sessionSid ?? parent?.sessionId,
+        traceId: input.traceId ?? parent?.traceId,
+        hop: parent?.hop ?? 0,
+    };
+    if (input.onAgentStart)
+        await input.onAgentStart(ctx);
+    try {
+        return await bind(ctx, fn);
+    }
+    finally {
+        if (input.onAgentEnd)
+            await input.onAgentEnd(ctx);
+        if (kind !== AgentKind.Service) {
+            await terminateAgent(input.coordinator, bearer, input.zoneId, res.agent_session_id);
+        }
+    }
+}
+export async function delegate(input, fn) {
+    const ctx = current();
+    if (!ctx)
+        throw new Error("delegate requires a Caracal context bound on this path");
+    if (!ctx.agentSessionId) {
+        throw new Error("delegate requires an active agent session in context");
+    }
+    const res = await createDelegation(input.coordinator, ctx.subjectToken, {
+        zoneId: ctx.zoneId,
+        issuerApplicationId: ctx.clientId,
+        sourceSessionId: ctx.agentSessionId,
+        targetSessionId: input.toAgentSessionId,
+        receiverApplicationId: input.toApplicationId,
+        scopes: input.scopes,
+        constraints: input.constraints,
+        ttlSeconds: input.ttlSeconds,
+    });
+    const child = {
+        ...ctx,
+        parentEdgeId: ctx.delegationEdgeId,
+        delegationEdgeId: res.delegation_edge_id,
+        hop: ctx.hop + 1,
+    };
+    return bind(child, fn);
+}
+//# sourceMappingURL=primitives.js.map

package/dist/primitives.js.map

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

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@caracalai/sdk",
+  "version": "0.1.0",
+  "description": "Caracal agent identity and delegation SDK.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/Garudex-Labs/caracal",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Garudex-Labs/caracal.git",
+    "directory": "packages/sdk/ts"
+  },
+  "keywords": ["caracal", "agent", "identity", "delegation", "sdk"],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./advanced": {
+      "import": "./dist/advanced.js",
+      "types": "./dist/advanced.d.ts"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --root ../../.. tests/typescript/unit/sdk/client.test.ts",
+    "prepublishOnly": "tsc"
+  },
+  "dependencies": {
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
+  }
+}