@you-agent-factory/client 0.0.0 → 0.0.1

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Port
+Copyright (c) 2026-2026 Andreas Abdi
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,19 +1,80 @@
 # `@you-agent-factory/client`
 
-Framework-neutral TypeScript contracts for You Agent Factory consumers.
-
-The package exports the generated OpenAPI `components`, `paths`, and
-`operations` namespaces together with stable `FactoryEvent`,
-`FactoryEventType`, `FactoryDefinition`, and `FactoryRecording` aliases.
-Generated symbols remain available through `@you-agent-factory/client/generated/openapi`.
-
-`parseFactoryRecording` validates unknown input against the canonical recording
-schema and replay-safe cross-event invariants, returning the original typed
-recording on success. It throws `FactoryRecordingValidationError` with
-structured issues on failure. `safeParseFactoryRecording` performs the same
-validation without throwing and returns a discriminated success or failure
-result.
-
-The chapter-free example recording is published as raw JSON at
-`@you-agent-factory/client/recordings/example`. It contains one Factory Session,
-the required topology bootstrap, and canonically ordered Factory Events.
+Transport-neutral Factory contracts and recording utilities for TypeScript
+consumers. The package has no React, browser, dashboard, or network dependency.
+See the [public package family guide](https://github.com/portpowered/you-agent-factory/blob/main/ui/packages/README.md)
+for its contract-layer role, dependency direction, supported integration paths,
+and hosted-execution boundary.
+
+## Stable contracts
+
+The root entry point exports the generated `components`, `paths`, and
+`operations` type namespaces together with stable `FactoryEvent`,
+`FactoryEventType`, and `FactoryDefinition` aliases. `FACTORY_EVENT_TYPES`
+provides the runtime event constants from the same generated contract.
+
+## Factory recordings
+
+`parseFactoryRecording` validates unknown input and returns a trusted
+`FactoryRecording`; invalid input throws `FactoryRecordingValidationError` with
+machine-readable issue codes and input paths. Use `safeParseFactoryRecording`
+for a discriminated result that never throws for invalid customer input. Both
+recording and replay parsing enforce the generated canonical Factory and
+discriminated Factory-event JSON Schemas, including formats, numeric limits,
+required payload fields, and additional-property rules.
+
+The packaged
+[`customer-support.factory-recording.v1.json`](examples/customer-support.factory-recording.v1.json)
+is a backend-free example of the public `factory-recording/v1` contract. It
+includes both a top-level Factory definition and a canonical topology event.
+
+## Replay helpers
+
+Replay consumers can use `orderFactoryEvents` for deterministic tick-first
+ordering, `createFactoryEventCursor` for reconnect positions, and
+`parseFactoryEventReplayText` (or its non-throwing safe-parser counterpart) to
+validate and order canonical JSON `data` frames from captured SSE text. These
+helpers are pure and do not open or retain a live transport.
+
+## Factory visualization layout sidecars
+
+`parseFactoryVisualizationLayout` validates optional, presentation-only
+metadata beside a read-only `FactoryDefinition`; the sidecar is never added to
+the canonical Factory. Version 1 carries positioned note and embedded-raster
+image annotations plus text or image empty states keyed by canonical topology
+node ID. Empty-state references are checked against the canonical topology
+projected from the supplied Factory, and blank, unknown, or duplicate node IDs
+are rejected. `safeParseFactoryVisualizationLayout` returns stable issue codes
+and input paths instead of throwing. The contract contains data only: no
+callback, URL, link, HTML, Markdown, topology connection, route, event,
+persistence, or runtime-effect field is supported.
+
+Embedded sources accept only PNG, JPEG, or WebP signatures encoded as strict
+canonical padded base64. Alternative text is required, each decoded image is
+limited to 2 MiB, and all image occurrences in one sidecar share an 8 MiB
+decoded-byte budget.
+
+The packaged
+[`customer-support.factory-visualization-layout.v1.json`](examples/customer-support.factory-visualization-layout.v1.json)
+demonstrates each version-1 variant independently from the canonical Factory.
+
+## Contract generation
+
+Run `bun run generate` from this directory after the checked-in dashboard
+OpenAPI TypeScript artifact changes. Run `bun run check:generated` to verify
+freshness without writing files. Both commands treat the generated OpenAPI
+TypeScript artifact and published Factory/Factory-event schemas as read-only
+inputs and write, when requested, only to
+`ui/packages/client/src/generated`.
+
+## Distribution verification
+
+Run `bun run build` to emit the ESM runtime and declarations in `dist`. Run
+`bun run check:pack` to build a registry-format tarball and verify its exact
+inventory, export targets, and declared runtime dependency boundary. Run
+`bun run check:installed-consumer` to install that tarball in a clean temporary
+project, typecheck the public contracts, and execute the recording, ordering,
+cursor, and replay helpers against the packaged customer example using only its
+declared runtime dependencies. `bun run
+verify` runs these checks after generation freshness, package typecheck, and
+focused tests.

package/dist/contracts.d.ts

@@ -0,0 +1,51 @@
+import { type components, type operations, type paths } from "./generated/openapi.js";
+export type { components, operations, paths };
+type FactorySchemas = components["schemas"];
+/** The canonical versioned event envelope exposed by the public client. */
+export type FactoryEvent = FactorySchemas["FactoryEvent"];
+/** The supported canonical Factory event type vocabulary. */
+export type FactoryEventType = FactorySchemas["FactoryEventType"];
+/** The customer-authored Factory topology definition. */
+export type FactoryDefinition = FactorySchemas["Factory"];
+/**
+ * Runtime Factory event constants generated from the canonical OpenAPI input.
+ * The object retains the generated keys and literal values without duplicating
+ * the event vocabulary in handwritten source.
+ */
+export declare const FACTORY_EVENT_TYPES: {
+    readonly FactoryEventTypeRunRequest: "RUN_REQUEST";
+    readonly FactoryEventTypeInitialStructureRequest: "INITIAL_STRUCTURE_REQUEST";
+    readonly FactoryEventTypeFactoryChange: "FACTORY_CHANGE";
+    readonly FactoryEventTypeWorkRequest: "WORK_REQUEST";
+    readonly FactoryEventTypeRelationshipChangeRequest: "RELATIONSHIP_CHANGE_REQUEST";
+    readonly FactoryEventTypeDispatchRequest: "DISPATCH_REQUEST";
+    readonly FactoryEventTypeModelRequest: "MODEL_REQUEST";
+    readonly FactoryEventTypeModelResponse: "MODEL_RESPONSE";
+    readonly FactoryEventTypeInferenceRequest: "INFERENCE_REQUEST";
+    readonly FactoryEventTypeInferenceResponse: "INFERENCE_RESPONSE";
+    readonly FactoryEventTypeScriptRequest: "SCRIPT_REQUEST";
+    readonly FactoryEventTypeScriptResponse: "SCRIPT_RESPONSE";
+    readonly FactoryEventTypeAgentRunResponse: "AGENT_RUN_RESPONSE";
+    readonly FactoryEventTypeDispatchResponse: "DISPATCH_RESPONSE";
+    readonly FactoryEventTypeWorkStateChange: "WORK_STATE_CHANGE";
+    readonly FactoryEventTypeFactoryStateResponse: "FACTORY_STATE_RESPONSE";
+    readonly FactoryEventTypeRunResponse: "RUN_RESPONSE";
+    readonly FactoryEventTypeSessionStarted: "SESSION_STARTED";
+    readonly FactoryEventTypeSessionPaused: "SESSION_PAUSED";
+    readonly FactoryEventTypeSessionResumed: "SESSION_RESUMED";
+    readonly FactoryEventTypeSessionResultUpdated: "SESSION_RESULT_UPDATED";
+    readonly FactoryEventTypeSessionCompleted: "SESSION_COMPLETED";
+    readonly FactoryEventTypeSessionLifecycleControl: "SESSION_LIFECYCLE_CONTROL";
+    readonly FactoryEventTypeOrchestratorPhaseChanged: "ORCHESTRATOR_PHASE_CHANGED";
+    readonly FactoryEventTypeOrchestratorCheckpointWritten: "ORCHESTRATOR_CHECKPOINT_WRITTEN";
+    readonly FactoryEventTypeDispatchQueued: "DISPATCH_QUEUED";
+    readonly FactoryEventTypeDispatchInterrupted: "DISPATCH_INTERRUPTED";
+    readonly FactoryEventTypeDispatchReconciled: "DISPATCH_RECONCILED";
+    readonly FactoryEventTypeJavaScriptCheckpointRef: "JAVASCRIPT_CHECKPOINT_REF";
+    readonly FactoryEventTypeJavaScriptPhaseChange: "JAVASCRIPT_PHASE_CHANGE";
+    readonly FactoryEventTypeArtifactCreated: "ARTIFACT_CREATED";
+};
+/** Runtime versions accepted by the canonical Factory event envelope. */
+export declare const FACTORY_EVENT_SCHEMA_VERSIONS: {
+    readonly agent_factory_event_v1: "agent-factory.event.v1";
+};

package/dist/contracts.js

@@ -0,0 +1,9 @@
+import { FactoryEventSchemaVersion as GENERATED_FACTORY_EVENT_SCHEMA_VERSIONS, FactoryEventType as GENERATED_FACTORY_EVENT_TYPES, } from "./generated/openapi.js";
+/**
+ * Runtime Factory event constants generated from the canonical OpenAPI input.
+ * The object retains the generated keys and literal values without duplicating
+ * the event vocabulary in handwritten source.
+ */
+export const FACTORY_EVENT_TYPES = GENERATED_FACTORY_EVENT_TYPES;
+/** Runtime versions accepted by the canonical Factory event envelope. */
+export const FACTORY_EVENT_SCHEMA_VERSIONS = GENERATED_FACTORY_EVENT_SCHEMA_VERSIONS;

package/dist/event-ordering.d.ts

@@ -0,0 +1,15 @@
+import type { FactoryEvent } from "./contracts.js";
+/** The reconnect position acknowledged by a downstream replay consumer. */
+export interface FactoryEventCursor {
+    afterEventId: string;
+    afterSequence: number;
+    tick: number;
+}
+/** Return the session-scoped sequence when available, otherwise the event-log sequence. */
+export declare function getFactoryEventEffectiveSequence(event: FactoryEvent): number;
+/** Compare canonical Factory events by replay position. */
+export declare function compareFactoryEvents(left: FactoryEvent, right: FactoryEvent): number;
+/** Return a canonically ordered copy without mutating caller-owned events or arrays. */
+export declare function orderFactoryEvents(events: readonly FactoryEvent[]): FactoryEvent[];
+/** Build the reconnect cursor acknowledged at an accepted Factory event. */
+export declare function createFactoryEventCursor(event: FactoryEvent): FactoryEventCursor;

package/dist/event-ordering.js

@@ -0,0 +1,33 @@
+/** Return the session-scoped sequence when available, otherwise the event-log sequence. */
+export function getFactoryEventEffectiveSequence(event) {
+    return event.context.sessionSequence ?? event.context.sequence;
+}
+/** Compare canonical Factory events by replay position. */
+export function compareFactoryEvents(left, right) {
+    const tickDifference = left.context.tick - right.context.tick;
+    if (tickDifference !== 0)
+        return tickDifference;
+    const sequenceDifference = getFactoryEventEffectiveSequence(left) -
+        getFactoryEventEffectiveSequence(right);
+    if (sequenceDifference !== 0)
+        return sequenceDifference;
+    const eventLogSequenceDifference = left.context.sequence - right.context.sequence;
+    if (eventLogSequenceDifference !== 0)
+        return eventLogSequenceDifference;
+    const timeDifference = left.context.eventTime.localeCompare(right.context.eventTime);
+    return timeDifference !== 0
+        ? timeDifference
+        : left.id.localeCompare(right.id);
+}
+/** Return a canonically ordered copy without mutating caller-owned events or arrays. */
+export function orderFactoryEvents(events) {
+    return [...events].sort(compareFactoryEvents);
+}
+/** Build the reconnect cursor acknowledged at an accepted Factory event. */
+export function createFactoryEventCursor(event) {
+    return {
+        afterEventId: event.id,
+        afterSequence: getFactoryEventEffectiveSequence(event),
+        tick: event.context.tick,
+    };
+}