@sentropic/h2a 0.1.0

package/README.md

@@ -0,0 +1,11 @@
+# @sentropic/h2a
+
+Core contracts and runtime primitives for `h2a`, a human-to-agent coordination model.
+
+Current bootstrap surface:
+
+- envelope creation and validation
+- negotiation state guards
+- canonical protocol constants
+
+Repository: <https://github.com/rhanka/h2a>

package/dist/envelope.d.ts

@@ -0,0 +1,8 @@
+import { type H2AEnvelope } from "./types.js";
+type CreateEnvelopeInput<TBody> = Omit<H2AEnvelope<TBody>, "protocol" | "version" | "createdAt"> & {
+    createdAt?: string;
+};
+export declare function createEnvelope<TBody>(input: CreateEnvelopeInput<TBody>): H2AEnvelope<TBody>;
+export declare function isH2AEnvelope<TBody = unknown>(value: unknown): value is H2AEnvelope<TBody>;
+export {};
+//# 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":"AAAA,OAAO,EAML,KAAK,WAAW,EAEjB,MAAM,YAAY,CAAC;AAEpB,KAAK,mBAAmB,CAAC,KAAK,IAAI,IAAI,CACpC,WAAW,CAAC,KAAK,CAAC,EAClB,UAAU,GAAG,SAAS,GAAG,WAAW,CACrC,GAAG;IACF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAwBF,wBAAgB,cAAc,CAAC,KAAK,EAClC,KAAK,EAAE,mBAAmB,CAAC,KAAK,CAAC,GAChC,WAAW,CAAC,KAAK,CAAC,CAOpB;AAED,wBAAgB,aAAa,CAAC,KAAK,GAAG,OAAO,EAC3C,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,WAAW,CAAC,KAAK,CAAC,CAc7B"}

package/dist/envelope.js

@@ -0,0 +1,38 @@
+import { H2A_ENVELOPE_TYPES, H2A_PROTOCOL, H2A_ROLES, H2A_VERSION } from "./types.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isEnvelopeType(value) {
+    return typeof value === "string" && H2A_ENVELOPE_TYPES.includes(value);
+}
+function isActorRef(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return (typeof value.instance === "string" &&
+        typeof value.scope === "string" &&
+        typeof value.role === "string" &&
+        H2A_ROLES.includes(value.role) &&
+        (value.mandate === undefined || typeof value.mandate === "string"));
+}
+export function createEnvelope(input) {
+    return {
+        protocol: H2A_PROTOCOL,
+        version: H2A_VERSION,
+        createdAt: input.createdAt ?? new Date().toISOString(),
+        ...input
+    };
+}
+export function isH2AEnvelope(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return (value.protocol === H2A_PROTOCOL &&
+        value.version === H2A_VERSION &&
+        typeof value.id === "string" &&
+        isEnvelopeType(value.type) &&
+        isActorRef(value.actor) &&
+        "body" in value &&
+        typeof value.createdAt === "string");
+}
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,SAAS,EACT,WAAW,EAIZ,MAAM,YAAY,CAAC;AASpB,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,kBAAkB,CAAC,QAAQ,CAAC,KAAwB,CAAC,CAAC;AAC5F,CAAC;AAED,SAAS,UAAU,CAAC,KAAc;IAChC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,CACL,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ;QAClC,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ;QAC/B,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;QAC9B,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,IAA2B,CAAC;QACrD,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,CACnE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,KAAiC;IAEjC,OAAO;QACL,QAAQ,EAAE,YAAY;QACtB,OAAO,EAAE,WAAW;QACpB,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACtD,GAAG,KAAK;KACT,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,KAAc;IAEd,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,CACL,KAAK,CAAC,QAAQ,KAAK,YAAY;QAC/B,KAAK,CAAC,OAAO,KAAK,WAAW;QAC7B,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ;QAC5B,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC;QAC1B,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC;QACvB,MAAM,IAAI,KAAK;QACf,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,CACpC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createEnvelope, isH2AEnvelope } from "./envelope.js";
+export { assertValidNegotiationState } from "./negotiation.js";
+export { H2A_ARTIFACT_KINDS, H2A_ENVELOPE_TYPES, H2A_NEGOTIATION_STATES, H2A_PROTOCOL, H2A_ROLES, H2A_VERSION } from "./types.js";
+export type { H2AActorRef, H2AActorRegistration, H2AArtifactKind, H2AEnvelope, H2AEnvelopeType, H2ANegotiationRecord, H2ANegotiationState, H2ARole, H2ASignature } from "./types.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":"AAAA,OAAO,EACL,cAAc,EACd,aAAa,EACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,YAAY,EACZ,SAAS,EACT,WAAW,EACZ,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,WAAW,EACX,oBAAoB,EACpB,eAAe,EACf,WAAW,EACX,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,OAAO,EACP,YAAY,EACb,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createEnvelope, isH2AEnvelope } from "./envelope.js";
+export { assertValidNegotiationState } from "./negotiation.js";
+export { H2A_ARTIFACT_KINDS, H2A_ENVELOPE_TYPES, H2A_NEGOTIATION_STATES, H2A_PROTOCOL, H2A_ROLES, H2A_VERSION } from "./types.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,OAAO,EACL,cAAc,EACd,aAAa,EACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,YAAY,EACZ,SAAS,EACT,WAAW,EACZ,MAAM,YAAY,CAAC"}

package/dist/negotiation.d.ts

@@ -0,0 +1,3 @@
+import { type H2ANegotiationState } from "./types.js";
+export declare function assertValidNegotiationState(state: string): H2ANegotiationState;
+//# sourceMappingURL=negotiation.d.ts.map

package/dist/negotiation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"negotiation.d.ts","sourceRoot":"","sources":["../src/negotiation.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,YAAY,CAAC;AAEpB,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,GACZ,mBAAmB,CAMrB"}

package/dist/negotiation.js

@@ -0,0 +1,8 @@
+import { H2A_NEGOTIATION_STATES } from "./types.js";
+export function assertValidNegotiationState(state) {
+    if (H2A_NEGOTIATION_STATES.includes(state)) {
+        return state;
+    }
+    throw new Error(`Unknown negotiation state: ${state}`);
+}
+//# sourceMappingURL=negotiation.js.map

package/dist/negotiation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"negotiation.js","sourceRoot":"","sources":["../src/negotiation.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EAEvB,MAAM,YAAY,CAAC;AAEpB,MAAM,UAAU,2BAA2B,CACzC,KAAa;IAEb,IAAI,sBAAsB,CAAC,QAAQ,CAAC,KAA4B,CAAC,EAAE,CAAC;QAClE,OAAO,KAA4B,CAAC;IACtC,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,8BAA8B,KAAK,EAAE,CAAC,CAAC;AACzD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,69 @@
+export declare const H2A_PROTOCOL = "sentropic.h2a";
+export declare const H2A_VERSION = "0.1";
+export declare const H2A_ROLES: readonly ["PRINCIPAL", "EXECUTIF", "CONDUCTOR", "AGENTS", "CONTROL", "MANDATAIRE"];
+export declare const H2A_ARTIFACT_KINDS: readonly ["CONTRACT", "POLICY", "ENGAGEMENT", "AMENDMENT"];
+export declare const H2A_ENVELOPE_TYPES: readonly ["register", "propose", "accept", "reject", "counter", "withdraw", "event", "escalate"];
+export declare const H2A_NEGOTIATION_STATES: readonly ["draft", "proposed", "countered", "accepted", "rejected", "withdrawn", "expired", "stabilized", "abandoned"];
+export type H2ARole = (typeof H2A_ROLES)[number];
+export type H2AArtifactKind = (typeof H2A_ARTIFACT_KINDS)[number];
+export type H2AEnvelopeType = (typeof H2A_ENVELOPE_TYPES)[number];
+export type H2ANegotiationState = (typeof H2A_NEGOTIATION_STATES)[number];
+export interface H2AActorRef {
+    instance: string;
+    role: H2ARole;
+    scope: string;
+    mandate?: string;
+}
+export interface H2ASignature {
+    by: string;
+    alg: string;
+    value: string;
+}
+export interface H2AEnvelope<TBody = unknown> {
+    protocol: typeof H2A_PROTOCOL;
+    version: typeof H2A_VERSION;
+    id: string;
+    type: H2AEnvelopeType;
+    actor: H2AActorRef;
+    target?: Partial<H2AActorRef>;
+    artifactKind?: H2AArtifactKind;
+    contractId?: string;
+    policyIds?: string[];
+    engagementId?: string;
+    negotiationId?: string;
+    baseArtifactHash?: string;
+    causationId?: string;
+    correlationId?: string;
+    prevHash?: string;
+    body: TBody;
+    createdAt: string;
+    signatures?: H2ASignature[];
+}
+export interface H2AActorRegistration {
+    id: string;
+    instance: string;
+    roles: H2ARole[];
+    scopes: string[];
+    principal?: string;
+    conductor?: string;
+    capabilities: string[];
+    endpoints: Array<{
+        kind: "mcp" | "local-files" | "remote";
+        uri: string;
+    }>;
+    publicKeys: string[];
+    acceptedPolicies: string[];
+    createdAt: string;
+}
+export interface H2ANegotiationRecord {
+    id: string;
+    scope: string;
+    parties: string[];
+    subject: "contract" | "policy" | "engagement" | "amendment";
+    status: H2ANegotiationState;
+    requiredSigners: string[];
+    baseArtifactHash?: string;
+    currentArtifactHash?: string;
+    deadline?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,38 @@
+export const H2A_PROTOCOL = "sentropic.h2a";
+export const H2A_VERSION = "0.1";
+export const H2A_ROLES = [
+    "PRINCIPAL",
+    "EXECUTIF",
+    "CONDUCTOR",
+    "AGENTS",
+    "CONTROL",
+    "MANDATAIRE"
+];
+export const H2A_ARTIFACT_KINDS = [
+    "CONTRACT",
+    "POLICY",
+    "ENGAGEMENT",
+    "AMENDMENT"
+];
+export const H2A_ENVELOPE_TYPES = [
+    "register",
+    "propose",
+    "accept",
+    "reject",
+    "counter",
+    "withdraw",
+    "event",
+    "escalate"
+];
+export const H2A_NEGOTIATION_STATES = [
+    "draft",
+    "proposed",
+    "countered",
+    "accepted",
+    "rejected",
+    "withdrawn",
+    "expired",
+    "stabilized",
+    "abandoned"
+];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,YAAY,GAAG,eAAe,CAAC;AAC5C,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,CAAC;AAEjC,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,WAAW;IACX,UAAU;IACV,WAAW;IACX,QAAQ;IACR,SAAS;IACT,YAAY;CACJ,CAAC;AAEX,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,UAAU;IACV,QAAQ;IACR,YAAY;IACZ,WAAW;CACH,CAAC;AAEX,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,UAAU;IACV,SAAS;IACT,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,UAAU;IACV,OAAO;IACP,UAAU;CACF,CAAC;AAEX,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,OAAO;IACP,UAAU;IACV,WAAW;IACX,UAAU;IACV,UAAU;IACV,WAAW;IACX,SAAS;IACT,YAAY;IACZ,WAAW;CACH,CAAC"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@sentropic/h2a",
+  "version": "0.1.0",
+  "description": "Core contracts and runtime primitives for human-to-agent coordination.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "keywords": [
+    "h2a",
+    "human-in-the-loop",
+    "multi-agent",
+    "coordination",
+    "negotiation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rhanka/h2a.git",
+    "directory": "packages/h2a"
+  },
+  "homepage": "https://github.com/rhanka/h2a#readme",
+  "bugs": {
+    "url": "https://github.com/rhanka/h2a/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}