octoflow-protocols

Dependency-free contracts shared by OctoFlow packages. Use this package directly when you are implementing a custom cognitive memory backend, execution environment, AG-UI adapter, or React transport that must satisfy the same interfaces used by octoflow-core, octoflow-brain, and @octoflow/react.

Install

npm install octoflow-protocols

Node.js >=20 is required.

Use It When

• You are writing a custom sandbox, runner, or execution backend.
• You are writing a custom cognitive memory implementation.
• You are writing a browser/client adapter that needs OctoFlow React or AG-UI shapes without importing the runtime.
• You need stable type contracts without importing concrete runtime implementations.
• You want version constants that let implementations fail fast on contract mismatch.

Most apps should install octoflow-core or octoflow-brain instead of importing this package directly.

What It Provides

| Contract | Includes | | ------------------------------ | ----------------------------------------------------------------------------------------------- | | Execution environment protocol | ExecutionEnvironment, ExecInput, ExecResult, SnapshotRef, EnvCapability. | | Memory protocol | CognitiveMemory, memory operation inputs/results, record types, replay types, embedder types. | | AG-UI protocol | AgUiCapabilities, OCTOFLOW_AGUI_CAPABILITIES, AGUI_COMPLIANCE_TARGET, lifecycle verifier result types. | | React transport contracts | OctoFlowChatEvent, OctoFlowUIMessage, approvals, sessions, provider catalog, transport capabilities. | | Version markers | EXECUTION_ENVIRONMENT_CONTRACT_VERSION, COGNITIVE_MEMORY_CONTRACT_VERSION. | | Shared close shape | CloseableResource for stores, layers, embedders, and other owned resources. |

Custom Execution Environment

import {
  EXECUTION_ENVIRONMENT_CONTRACT_VERSION,
  type EnvCapability,
  type ExecInput,
  type ExecResult,
  type ExecutionEnvironment,
} from 'octoflow-protocols';

class InternalSandboxEnvironment implements ExecutionEnvironment {
  readonly contractVersion = EXECUTION_ENVIRONMENT_CONTRACT_VERSION;
  readonly name = 'internal-sandbox';
  readonly capabilities: readonly EnvCapability[] = ['sdk-backed', 'sandboxed'];

  async exec(input: ExecInput): Promise<ExecResult> {
    // Dispatch to your sandbox API.
    return {
      stdout: '',
      stderr: '',
      exitCode: 0,
      truncated: false,
      timedOut: false,
      durationMs: 0,
    };
  }

  async cleanup(): Promise<void> {
    // Release pooled resources.
  }
}

Custom Memory Backend

import {
  COGNITIVE_MEMORY_CONTRACT_VERSION,
  type CognitiveMemory,
  type RecallInput,
  type RecallResult,
  type RememberInput,
  type RememberResult,
} from 'octoflow-protocols';

class MyMemoryBackend implements CognitiveMemory {
  readonly contractVersion = COGNITIVE_MEMORY_CONTRACT_VERSION;

  async remember(input: RememberInput): Promise<RememberResult> {
    throw new Error(`Implement remember for ${input.text}`);
  }

  async recall(input: RecallInput): Promise<RecallResult> {
    throw new Error(`Implement recall for ${input.query}`);
  }

  // Implement the remaining CognitiveMemory methods before using this class.
}

Implementations should hard-fail when the contract version they target does not match the runtime they attach to.

Learn More

• ../octoflow-core/README.md - reference execution environment and AG-UI gateway integrations.
• ../octoflow-react/README.md - browser-safe hooks and AG-UI/AI SDK UI adapter docs.
• ../octoflow-brain/README.md - reference CognitiveMemory implementation.
• ../../docs/security.md - execution policy and sandboxing context.
• ../../docs/brain.md - memory runtime context.
• ../octoflow-examples/src/execution - runnable execution environment examples.
• ../octoflow-examples/src/brain - runnable memory examples.

Validate

npm run -w octoflow-protocols lint
npm run -w octoflow-protocols typecheck
npm run -w octoflow-protocols test

Status

Preview. Pin versions and read ../../CHANGELOG.md before depending on it in production.