wefta

Shared runtime substrate for Wefta.

Current first-cut scope:

• normalized runtime/session contracts;
• backend adapter interfaces;
• root SDK owner for lifecycle, sessions, auth, history, tools, and backend inspection;
• public tool-trace and normalized tool-history API;
• explicit human-input lifecycle, including backend-cleared pending questions and approvals;
• runtime-normalized state helpers.

This package does not own the running session host implementation or deployment topology.

The architectural split is:

• wefta defines shared runtime contracts, adapters, and normalized state;
• wefta exposes one root SDK owner as the canonical public in-process API;
• products or transports may wrap that runtime with HTTP, SSE, IPC, or other boundaries as needed.

Public API

The intended product-facing surface is:

• backend objects from backend packages such as createClaude(), createCodex(), and createOpenCode();
• createAgentSdk() as the root owner;
• sdk.sessions for live session creation, lookup, and listing;
• sdk.auth for backend-native auth status/method/start/complete/cancel flows;
• sdk.history for persisted session listing and normalized timeline reads;
• sdk.tools for backend-scoped discovery and local tool registration;
• sdk.backends for backend readiness and model-catalog inspection;
• normalized tool lifecycle through tool.changed runtime events and snapshot.toolCalls;
• AgentSession handles for send, answer, approval, interrupt, snapshot, and event subscription.

Backend packages may implement AgentProfileAuth for one profile-scoped native auth lifecycle; backend adapters expose that through AgentBackendAuth, which accepts runtime fields such as cwd, env, and profileId.

The canonical interaction model is:

import { createAgentSdk, defineAgentLocalTool } from 'wefta';
import { createClaude } from '@wefta/claude';

const sdk = createAgentSdk({
  backend: createClaude(),
});

await sdk.start();

await sdk.tools.registerLocal({
  tools: [
    defineAgentLocalTool({
      name: 'echo',
      description: 'Echo text.',
      inputSchema: {},
      handler: () => ({
        text: 'ok',
      }),
    }),
  ],
});

const session = await sdk.sessions.create({
  model: 'claude-opus-4-7',
  reasoning: 'high',
  title: 'Refactor auth flow',
});

await session.send({
  text: 'Use the echo tool and then continue.',
  backendOptions: {
    thinking: { type: 'enabled', budgetTokens: 4000 },
  },
});

One AgentSession owns one active run at a time. Products that need many parallel runs should create many sessions rather than sending overlapping runs through one session handle.

Use session.startRun(request) when product code needs to wait on, inspect, or subscribe to one specific run. The returned AgentRun is scoped to the new runId, so its event stream excludes stale replay events from earlier runs in the same session.

Single-backend products do not need backend IDs at all. Multi-backend products may choose backend IDs through sdk.backends and pass backendId into session, auth, history, backend, or tool calls when a concrete backend must be selected.

Products that run one SDK instance across multiple workspaces or credential profiles pass flat runtime fields directly into those calls:

await sdk.sessions.create({
  backendId: 'codex',
  cwd: '/workspace/app',
  env: {
    CODEX_HOME: '/home/me/.wefta/profiles/work/codex',
  },
  profileId: 'work',
});

Do not pass SDK factories around product services. Create the SDK once at the runtime owner boundary, then pass the SDK instance and supply cwd, env, and profileId per operation.

Boundary Rules

• backend adapters own native boot/auth/protocol/session mechanics;
• backend adapters also own native persisted-history mechanics;
• backend adapters also own native tool discovery and local tool-registration mechanics;
• wefta owns normalized runtime semantics such as runs, events, approvals/questions, tools, artifacts, usage, backend refs, runtime snapshots, the root SDK owner, and the shared history/tools/backend services exposed from that owner;
• products own business semantics and should not read backend-native quirks directly.

Where and how a transport or deployment host runs is not part of the core SDK contract. Backends advertise normalized runtime capabilities. Products may add their own local/hosted/topology metadata above the core runtime layer.

Guidance For Future Adapters

When adding a real adapter:

• keep backend-native session/process IDs inside adapter state and expose only normalized refs through refs;
• translate backend-native events into AgentRuntimeSignal instead of leaking provider SDK payloads;
• translate backend-native persisted history into normalized history sessions and timeline events instead of leaking raw message/turn/part structures;
• use capabilities to describe normalized runtime behavior, not deployment topology or product meaning;
• treat interrupt/question/approval support as explicit adapter behavior rather than implied by product code.

Guidance For Future Products

Products should consume the shared runtime/session API plus normalized snapshots/events, and the shared history API for persisted browsing. Products should not:

• treat backend-native IDs as product IDs;
• assume one backend-specific auth/session model;
• re-encode runtime lifecycle semantics in product-local glue;
• infer persisted history from live runtime-only APIs;
• infer backend tool support from ad hoc backend options instead of using the shared tooling API;
• pass harness-native bags such as runtimeOptions, threadDefaults, or promptDefaults through the shared SDK API;
• depend on backend ID strings as the canonical single-backend session-creation primitive.