@codesoul-co/hypha-core / contracts/runtime-activities

• Package index: @codesoul-co/hypha-core
• Source: packages/core/src/contracts/runtime-activities.ts
• Exports: 20

Using this module

Use the Runtime activities module for declaring and runtime-validating contracts. It exports 3 constants, 9 interfaces, 8 types.

Import from the package entrypoint

import {
  RUNTIME_ACTIVITY_EFFECTS,
  RUNTIME_ACTIVITY_OBSERVATION_STATUSES,
  RUNTIME_ACTIVITY_TYPES,
} from '@codesoul-co/hypha-core';

import type {
  RuntimeActivityDispatchPort,
  RuntimeActivityHelper,
  RuntimeActivityInvocation,
  RuntimeActivityLifecycleCommitPort,
  RuntimeActivityLifecycleCommitRequest,
  RuntimeActivityObservation,
  RuntimeActivityOptions,
  RuntimeActivityRequest,
} from '@codesoul-co/hypha-core';

// The complete export list is documented below.

Usage patterns

• Use the 17 type/interface exports as static contracts in application code, adapters, or tests. Import them with import type; they do not exist at runtime.
• The 3 constant/enum exports provide stable values, schemas, definitions, or defaults. Reuse these exports instead of copying internal values into an application.

Public exports

Symbol	Kind	Signature	Description
RUNTIME_ACTIVITY_EFFECTS	constant	const RUNTIME_ACTIVITY_EFFECTS: readonly ["pure", "idempotent", "external_effect", "irreversible"]	RUNTIME ACTIVITY EFFECTS constant exported by the contracts/runtime-activities module.
RUNTIME_ACTIVITY_OBSERVATION_STATUSES	constant	const RUNTIME_ACTIVITY_OBSERVATION_STATUSES: readonly ["completed", "failed", "waiting", "cancelled"]	RUNTIME ACTIVITY OBSERVATION STATUSES constant exported by the contracts/runtime-activities module.
RUNTIME_ACTIVITY_TYPES	constant	const RUNTIME_ACTIVITY_TYPES: readonly ["tool", "memory", "model", "execution", "custom"]	RUNTIME ACTIVITY TYPES constant exported by the contracts/runtime-activities module.
RuntimeActivityDispatchPort	interface	interface RuntimeActivityDispatchPort	Runtime Activity Dispatch Port interface with 1 public fields or methods.
RuntimeActivityHelper	interface	interface RuntimeActivityHelper	Runtime Activity Helper interface with 5 public fields or methods.
RuntimeActivityInvocation	interface	interface RuntimeActivityInvocation	Runtime Activity Invocation interface with 17 public fields or methods.
RuntimeActivityLifecycleCommitPort	interface	interface RuntimeActivityLifecycleCommitPort	Runtime Activity Lifecycle Commit Port interface with 1 public fields or methods.
RuntimeActivityLifecycleCommitRequest	interface	interface RuntimeActivityLifecycleCommitRequest	Runtime Activity Lifecycle Commit Request interface with 4 public fields or methods.
RuntimeActivityObservation	interface	interface RuntimeActivityObservation	Runtime Activity Observation interface with 8 public fields or methods.
RuntimeActivityOptions	interface	interface RuntimeActivityOptions	Runtime Activity Options interface with 6 public fields or methods.
RuntimeActivityRequest	interface	interface RuntimeActivityRequest	Runtime Activity Request interface with 3 public fields or methods.
RuntimeActivityRetryOptions	interface	interface RuntimeActivityRetryOptions	Runtime Activity Retry Options interface with 3 public fields or methods.
RuntimeActivityEffect	type	type RuntimeActivityEffect = (typeof RUNTIME_ACTIVITY_EFFECTS)[number]	Public type alias for Runtime Activity Effect; the declaration contains its complete type expression.
RuntimeActivityObservationStatus	type	type RuntimeActivityObservationStatus = (typeof RUNTIME_ACTIVITY_OBSERVATION_STATUSES)[number]	Public type alias for Runtime Activity Observation Status; the declaration contains its complete type expression.
RuntimeActivityType	type	type RuntimeActivityType = (typeof RUNTIME_ACTIVITY_TYPES)[number]	Public type alias for Runtime Activity Type; the declaration contains its complete type expression.
RuntimeCustomActivityRequest	type	type RuntimeCustomActivityRequest = RuntimeActivityRequest<TInput>	Public type alias for Runtime Custom Activity Request; the declaration contains its complete type expression.
RuntimeExecutionActivityRequest	type	type RuntimeExecutionActivityRequest = RuntimeActivityRequest<TInput>	Public type alias for Runtime Execution Activity Request; the declaration contains its complete type expression.
RuntimeMemoryActivityRequest	type	type RuntimeMemoryActivityRequest = RuntimeActivityRequest<TInput>	Public type alias for Runtime Memory Activity Request; the declaration contains its complete type expression.
RuntimeModelActivityRequest	type	type RuntimeModelActivityRequest = RuntimeActivityRequest<TInput>	Public type alias for Runtime Model Activity Request; the declaration contains its complete type expression.
RuntimeToolActivityRequest	type	type RuntimeToolActivityRequest = RuntimeActivityRequest<TInput>	Public type alias for Runtime Tool Activity Request; the declaration contains its complete type expression.

RUNTIME_ACTIVITY_EFFECTS

RUNTIME ACTIVITY EFFECTS constant exported by the contracts/runtime-activities module.

• Kind: constant
• Import: import { RUNTIME_ACTIVITY_EFFECTS } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export declare const RUNTIME_ACTIVITY_EFFECTS: readonly ["pure", "idempotent", "external_effect", "irreversible"];

RUNTIME_ACTIVITY_OBSERVATION_STATUSES

RUNTIME ACTIVITY OBSERVATION STATUSES constant exported by the contracts/runtime-activities module.

• Kind: constant
• Import: import { RUNTIME_ACTIVITY_OBSERVATION_STATUSES } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export declare const RUNTIME_ACTIVITY_OBSERVATION_STATUSES: readonly ["completed", "failed", "waiting", "cancelled"];

RUNTIME_ACTIVITY_TYPES

RUNTIME ACTIVITY TYPES constant exported by the contracts/runtime-activities module.

• Kind: constant
• Import: import { RUNTIME_ACTIVITY_TYPES } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export declare const RUNTIME_ACTIVITY_TYPES: readonly ["tool", "memory", "model", "execution", "custom"];

RuntimeActivityDispatchPort

Runtime Activity Dispatch Port interface with 1 public fields or methods.

• Kind: interface
• Import: import type { RuntimeActivityDispatchPort } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export interface RuntimeActivityDispatchPort {
    dispatch(invocation: RuntimeActivityInvocation, abortSignal: AbortSignal): Promise<RuntimeActivityObservation>;
}

Contract members

Member	Kind	Signature	Description
dispatch	method	dispatch(invocation: RuntimeActivityInvocation, abortSignal: AbortSignal): Promise<RuntimeActivityObservation>	Public method; parameters and return type are shown in the signature.

RuntimeActivityHelper

Runtime Activity Helper interface with 5 public fields or methods.

• Kind: interface
• Import: import type { RuntimeActivityHelper } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export interface RuntimeActivityHelper {
    tool(request: RuntimeToolActivityRequest): Promise<RuntimeActivityObservation>;
    memory(request: RuntimeMemoryActivityRequest): Promise<RuntimeActivityObservation>;
    model(request: RuntimeModelActivityRequest): Promise<RuntimeActivityObservation>;
    execution(request: RuntimeExecutionActivityRequest): Promise<RuntimeActivityObservation>;
    custom(request: RuntimeCustomActivityRequest): Promise<RuntimeActivityObservation>;
}

Contract members

Member	Kind	Signature	Description
custom	method	custom(request: RuntimeCustomActivityRequest): Promise<RuntimeActivityObservation>	Public method; parameters and return type are shown in the signature.
execution	method	execution(request: RuntimeExecutionActivityRequest): Promise<RuntimeActivityObservation>	Public method; parameters and return type are shown in the signature.
memory	method	memory(request: RuntimeMemoryActivityRequest): Promise<RuntimeActivityObservation>	Public method; parameters and return type are shown in the signature.
model	method	model(request: RuntimeModelActivityRequest): Promise<RuntimeActivityObservation>	Public method; parameters and return type are shown in the signature.
tool	method	tool(request: RuntimeToolActivityRequest): Promise<RuntimeActivityObservation>	Public method; parameters and return type are shown in the signature.

RuntimeActivityInvocation

Runtime Activity Invocation interface with 17 public fields or methods.

• Kind: interface
• Import: import type { RuntimeActivityInvocation } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export interface RuntimeActivityInvocation<TInput extends RuntimeJsonValue = RuntimeJsonValue> {
    activityId: string;
    operationId: string;
    activityType: RuntimeActivityType;
    target: string;
    input: TInput;
    scope: RuntimeScope;
    stateId: string;
    stateAttempt: number;
    fencingToken: number;
    correlationId: string;
    causationId?: string;
    idempotencyKey: string;
    requestedAt: string;
    effect: RuntimeActivityEffect;
    timeoutMs?: number;
    retry?: RuntimeActivityRetryOptions;
    metadata?: Record<string, RuntimeJsonValue>;
}

Contract members

Member	Kind	Signature	Description
activityId	property	activityId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
activityType	property	activityType: "memory" | "tool" | "model" | "custom" | "execution"	Public property; its type, readonly modifier and optionality are shown in the signature.
causationId	property	causationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
correlationId	property	correlationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
effect	property	effect: "external_effect" | "irreversible" | "pure" | "idempotent"	Public property; its type, readonly modifier and optionality are shown in the signature.
fencingToken	property	fencingToken: number	Public property; its type, readonly modifier and optionality are shown in the signature.
idempotencyKey	property	idempotencyKey: string	Public property; its type, readonly modifier and optionality are shown in the signature.
input	property	input: TInput	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, RuntimeJsonValue>	Public property; its type, readonly modifier and optionality are shown in the signature.
operationId	property	operationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
requestedAt	property	requestedAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
retry	property	retry?: RuntimeActivityRetryOptions	Public property; its type, readonly modifier and optionality are shown in the signature.
scope	property	scope: RuntimeScope	Public property; its type, readonly modifier and optionality are shown in the signature.
stateAttempt	property	stateAttempt: number	Public property; its type, readonly modifier and optionality are shown in the signature.
stateId	property	stateId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
target	property	target: string	Public property; its type, readonly modifier and optionality are shown in the signature.
timeoutMs	property	timeoutMs?: number	Public property; its type, readonly modifier and optionality are shown in the signature.

RuntimeActivityLifecycleCommitPort

Runtime Activity Lifecycle Commit Port interface with 1 public fields or methods.

• Kind: interface
• Import: import type { RuntimeActivityLifecycleCommitPort } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export interface RuntimeActivityLifecycleCommitPort {
    append(request: RuntimeActivityLifecycleCommitRequest): Promise<FrameworkEvent>;
}

Contract members

Member	Kind	Signature	Description
append	method	append(request: RuntimeActivityLifecycleCommitRequest): Promise<FrameworkEvent>	Public method; parameters and return type are shown in the signature.

RuntimeActivityLifecycleCommitRequest

Runtime Activity Lifecycle Commit Request interface with 4 public fields or methods.

• Kind: interface
• Import: import type { RuntimeActivityLifecycleCommitRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export interface RuntimeActivityLifecycleCommitRequest {
    execution: RuntimeHelperExecutionScope;
    event: EventCreateInput;
    fencingToken: number;
    idempotencyKey: string;
}

Contract members

Member	Kind	Signature	Description
event	property	event: EventCreateInput<unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
execution	property	execution: RuntimeHelperExecutionScope	Public property; its type, readonly modifier and optionality are shown in the signature.
fencingToken	property	fencingToken: number	Public property; its type, readonly modifier and optionality are shown in the signature.
idempotencyKey	property	idempotencyKey: string	Public property; its type, readonly modifier and optionality are shown in the signature.

RuntimeActivityObservation

Runtime Activity Observation interface with 8 public fields or methods.

• Kind: interface
• Import: import type { RuntimeActivityObservation } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export interface RuntimeActivityObservation<TOutput extends RuntimeJsonValue = RuntimeJsonValue> {
    activityId: string;
    status: RuntimeActivityObservationStatus;
    eventIds: string[];
    output?: TOutput;
    artifactRefs?: string[];
    retryable?: boolean;
    error?: NormalizedRuntimeError;
    metadata?: Record<string, RuntimeJsonValue>;
}

Contract members

Member	Kind	Signature	Description
activityId	property	activityId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
artifactRefs	property	artifactRefs?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
error	property	error?: NormalizedRuntimeError	Public property; its type, readonly modifier and optionality are shown in the signature.
eventIds	property	eventIds: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, RuntimeJsonValue>	Public property; its type, readonly modifier and optionality are shown in the signature.
output	property	output?: TOutput	Public property; its type, readonly modifier and optionality are shown in the signature.
retryable	property	retryable?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
status	property	status: "completed" | "cancelled" | "failed" | "waiting"	Public property; its type, readonly modifier and optionality are shown in the signature.

RuntimeActivityOptions

Runtime Activity Options interface with 6 public fields or methods.

• Kind: interface
• Import: import type { RuntimeActivityOptions } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export interface RuntimeActivityOptions {
    effect?: RuntimeActivityEffect;
    timeoutMs?: number;
    retry?: RuntimeActivityRetryOptions;
    idempotencyKey?: string;
    causationId?: string;
    metadata?: Record<string, RuntimeJsonValue>;
}

Contract members

Member	Kind	Signature	Description
causationId	property	causationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
effect	property	effect?: "external_effect" | "irreversible" | "pure" | "idempotent"	Public property; its type, readonly modifier and optionality are shown in the signature.
idempotencyKey	property	idempotencyKey?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, RuntimeJsonValue>	Public property; its type, readonly modifier and optionality are shown in the signature.
retry	property	retry?: RuntimeActivityRetryOptions	Public property; its type, readonly modifier and optionality are shown in the signature.
timeoutMs	property	timeoutMs?: number	Public property; its type, readonly modifier and optionality are shown in the signature.

RuntimeActivityRequest

Runtime Activity Request interface with 3 public fields or methods.

• Kind: interface
• Import: import type { RuntimeActivityRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export interface RuntimeActivityRequest<TInput extends RuntimeJsonValue = RuntimeJsonValue> {
    target: string;
    input: TInput;
    options?: RuntimeActivityOptions;
}

Contract members

Member	Kind	Signature	Description
input	property	input: TInput	Public property; its type, readonly modifier and optionality are shown in the signature.
options	property	options?: RuntimeActivityOptions	Public property; its type, readonly modifier and optionality are shown in the signature.
target	property	target: string	Public property; its type, readonly modifier and optionality are shown in the signature.

RuntimeActivityRetryOptions

Runtime Activity Retry Options interface with 3 public fields or methods.

• Kind: interface
• Import: import type { RuntimeActivityRetryOptions } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export interface RuntimeActivityRetryOptions {
    maxAttempts: number;
    initialDelayMs?: number;
    maxDelayMs?: number;
}

Contract members

Member	Kind	Signature	Description
initialDelayMs	property	initialDelayMs?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxAttempts	property	maxAttempts: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxDelayMs	property	maxDelayMs?: number	Public property; its type, readonly modifier and optionality are shown in the signature.

RuntimeActivityEffect

Public type alias for Runtime Activity Effect; the declaration contains its complete type expression.

• Kind: type
• Import: import type { RuntimeActivityEffect } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export type RuntimeActivityEffect = (typeof RUNTIME_ACTIVITY_EFFECTS)[number];

RuntimeActivityObservationStatus

Public type alias for Runtime Activity Observation Status; the declaration contains its complete type expression.

• Kind: type
• Import: import type { RuntimeActivityObservationStatus } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export type RuntimeActivityObservationStatus = (typeof RUNTIME_ACTIVITY_OBSERVATION_STATUSES)[number];

RuntimeActivityType

Public type alias for Runtime Activity Type; the declaration contains its complete type expression.

• Kind: type
• Import: import type { RuntimeActivityType } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export type RuntimeActivityType = (typeof RUNTIME_ACTIVITY_TYPES)[number];

RuntimeCustomActivityRequest

Public type alias for Runtime Custom Activity Request; the declaration contains its complete type expression.

• Kind: type
• Import: import type { RuntimeCustomActivityRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export type RuntimeCustomActivityRequest<TInput extends RuntimeJsonValue = RuntimeJsonValue> = RuntimeActivityRequest<TInput>;

RuntimeExecutionActivityRequest

Public type alias for Runtime Execution Activity Request; the declaration contains its complete type expression.

• Kind: type
• Import: import type { RuntimeExecutionActivityRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export type RuntimeExecutionActivityRequest<TInput extends RuntimeJsonValue = RuntimeJsonValue> = RuntimeActivityRequest<TInput>;

RuntimeMemoryActivityRequest

Public type alias for Runtime Memory Activity Request; the declaration contains its complete type expression.

• Kind: type
• Import: import type { RuntimeMemoryActivityRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export type RuntimeMemoryActivityRequest<TInput extends RuntimeJsonValue = RuntimeJsonValue> = RuntimeActivityRequest<TInput>;

RuntimeModelActivityRequest

Public type alias for Runtime Model Activity Request; the declaration contains its complete type expression.

• Kind: type
• Import: import type { RuntimeModelActivityRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export type RuntimeModelActivityRequest<TInput extends RuntimeJsonValue = RuntimeJsonValue> = RuntimeActivityRequest<TInput>;

RuntimeToolActivityRequest

Public type alias for Runtime Tool Activity Request; the declaration contains its complete type expression.

• Kind: type
• Import: import type { RuntimeToolActivityRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/runtime-activities

Declaration

export type RuntimeToolActivityRequest<TInput extends RuntimeJsonValue = RuntimeJsonValue> = RuntimeActivityRequest<TInput>;