eve/dist/src/runtime/attributes/emit.d.ts

Filesystem-first framework for durable backend AI agents that run anywhere.

import "#internal/workflow/builtins.js";
/**
 * Maximum byte size for an attribute value on a workflow run.
 *
 * Local mirror of `ATTRIBUTE_VALUE_MAX_BYTES` from `@workflow/world`
 * (source of truth: `packages/world/src/attributes.ts` in the workflow
 * repo). The value is duplicated rather than imported because
 * `@workflow/core` — the only workflow surface bundled into the
 * workflow body — does not re-export it, and pulling `@workflow/world`
 * into the body bundle would drag in the full zod attribute validator
 * (the same reason `workflow-core-shim.ts` skips runtime validation in
 * its `experimental_setAttributes`).
 *
 * Strings emitted through {@link setEveAttributes} are truncated to this
 * byte count before they reach the runtime so the validator never
 * rejects a tag for length alone.
 *
 * Drift is conservative-by-construction: if workflow LOWERS the limit,
 * over-long values are rejected and `setEveAttributes` swallows the
 * failure (warn-once-per-process) — dashboards see a missing tag, never
 * a broken agent; if workflow RAISES it, titles are merely shorter than
 * necessary. `emit.drift.test.ts` asserts equality against the real
 * `@workflow/world` export (a devDependency) so CI fails loudly the day
 * the constants diverge.
 */
export declare const EVE_ATTRIBUTE_VALUE_MAX_BYTES = 256;
/**
 * Attribute value the caller wants to write. `undefined` values are
 * stripped before the runtime call; numbers are stringified; strings
 * are truncated to {@link EVE_ATTRIBUTE_VALUE_MAX_BYTES}.
 */
export type EveAttributeValue = string | number | undefined;
/**
 * Truncates a string so its UTF-8 byte length is at most `maxBytes`
 * without splitting a multi-byte character.
 *
 * The workflow runtime measures attribute values in UTF-8 bytes, not
 * code units, so `value.slice(0, maxBytes)` is not safe — a JS string
 * with two-byte characters (e.g. emoji surrogate pairs) can serialize
 * to twice as many bytes as code units. We re-encode the truncated
 * candidate after each drop and shrink one code unit at a time when
 * the candidate's last character straddles the byte budget.
 */
export declare function truncateForTag(value: string, maxBytes?: number): string;
/**
 * Writes a batch of eve-owned attributes to the active workflow run.
 *
 * Reserved-namespace contract:
 * - All keys must use the `$eve.` prefix (the workflow runtime would
 *   otherwise reject them as user-space writes into the reserved `$`
 *   namespace).
 * - The call always opts in via `{ allowReservedAttributes: true }`
 *   on behalf of the framework — authored code never calls this helper
 *   directly.
 *
 * Value normalization:
 * - `undefined` entries are dropped so callers can build attribute
 *   maps with optional fields (`$eve.subagent` is only present on
 *   subagent roots, for example).
 * - Numbers are stringified (the runtime stores all values as strings).
 * - Strings are truncated to {@link EVE_ATTRIBUTE_VALUE_MAX_BYTES} via
 *   {@link truncateForTag} so a long free-form value (e.g. `$eve.title`)
 *   can never trip the runtime's per-value byte budget.
 *
 * Failure policy: tag writes are observability metadata, not load-bearing
 * state. A failure inside the runtime (transient network, schema bug,
 * missing world adapter) is logged once per process and then swallowed
 * so the eve session it tagged is unaffected.
 *
 * Must be called from inside a `"use workflow"` or `"use step"` body —
 * the runtime throws a `FatalError` outside those contexts.
 */
export declare function setEveAttributes(attrs: Record<string, EveAttributeValue>): Promise<void>;