Wormhole SDK

Wormhole SDK is the public Python interface for the Wormhole core engine.

Install (development)

pip install -e packages/sdk

Basic Usage

import asyncio
from wormhole_sdk import WormholeClient, ModelEventType

async def main():
    client = WormholeClient()
    async for event in client.send_message("Hello"):
        if event.type is ModelEventType.TEXT_DELTA:
            print(event.payload["text"], end="")
    print()

asyncio.run(main())

Tools

from wormhole_sdk import ModelEventType, ToolDefinition, WormholeClient

client = WormholeClient()

tool = ToolDefinition(tool_id="echo", name="Echo", schema={"type": "object"})

async def handler(args: dict) -> str:
    return str(args)

await client.register_tool(tool, handler)

async for event in client.send_message("Echo this", allowlist=["echo"]):
    if event.type is ModelEventType.TOOL_CALL:
        print(event.payload["tool_name"])

Task Delegation (TaskTool)

TaskTool delegates a sub-task to a fresh child session and returns a structured summary (status, result, child_session_id, and child tool-call summary).

from wormhole_sdk import SDKConfig, WormholeClient
from wormhole_sdk.tools.task import (
    TaskToolConfig,
    create_task_handler,
    create_task_tool,
)

client = WormholeClient(SDKConfig(adapter=my_adapter, persist_sessions=False))
task_config = TaskToolConfig(
    max_depth=3,
    default_max_steps=25,
    default_timeout_seconds=None,  # wall-clock timeout disabled unless configured
    default_locked_layers=["identity", "mandates", "safety"],
    allow_recursive_task=False,
)
await client.register_tool(
    create_task_tool(task_config),
    create_task_handler(client=client, task_tool_config=task_config),
)

Invocation pattern from the parent model:

{
  "task": "Explore the repo and summarize flaky tests",
  "system_prompt": "Focus on tests only",
  "tools": ["file_read", "bash"],
  "max_steps": 12,
  "timeout_seconds": 300
}

Behavior notes:

• Child sessions start with fresh history; parent context is passed via task text.
• Locked layers (identity, mandates, safety by default) remain immutable in child prompt customization.
• Approval-gated child tool calls use the same approval channel/cache as parent flow.
• Timeout grace-mode uses tools-disabled recovery before returning a structured timeout result.

Examples

See packages/sdk/examples/README.md for runnable chat and tool demos.

Configuration

from wormhole_sdk import RetryPolicy, SDKConfig, WormholeClient

config = SDKConfig(
    timeout_seconds=60.0,
    max_consecutive_steps=50,
    continue_on_max_tokens=True,
    retry_policy=RetryPolicy(max_retries=2, base_delay=1.0),
)

client = WormholeClient(config=config)

External Tool Registration

Use three separate concepts:

• tool_config_paths: discovery-only list of Python module paths.
• tools: registration list of tool_id strings for this client.
• allowlist/default_allowlist: execution-time gate during send_message.

from wormhole_sdk import SDKConfig, WormholeClient
from wormhole_sdk.tools import TOOL_BASH

config = SDKConfig(
    adapter=my_adapter,
    tool_config_paths=["my_tools.echo_tool"],  # discover external tools
    tools=[TOOL_BASH, "echo"],  # register built-in + external IDs
)
client = WormholeClient(config)

# Optional execution-time allowlist (separate from registration)
async for event in client.send_message("run echo", allowlist=["echo"]):
    print(event.type)

Rules:

• Unknown tool_id in tools fails fast at initialization.
• tool_config_paths import/factory/version failures fail fast at initialization.
• List ordering does not change registration behavior.
• Empty tools means no tools are registered.

Storage Providers and Session Persistence

from wormhole_sdk import SDKConfig, WormholeClient

# Default: file-based persistence in .wormhole/
client = WormholeClient(SDKConfig(adapter=my_adapter))

# Memory-only mode
client = WormholeClient(SDKConfig(adapter=my_adapter, persist_sessions=False))

# Manual-save mode
client = WormholeClient(
    SDKConfig(adapter=my_adapter, persist_sessions=True, auto_save=False)
)
await client.save_session("session-1")
sessions = await client.list_sessions()
await client.delete_session("session-1")

Custom providers can be supplied via SDKConfig.storage_provider with the four storage protocol implementations (session, execution state, event log, compaction).

Compaction and Forking

from wormhole_sdk import SDKConfig, WormholeClient

# Auto-compaction is enabled by default when a context limit is provided.
client = WormholeClient(SDKConfig(compaction_context_limit=200_000))

# Manual compaction (summary injected as a SYSTEM message)
result = await client.compact_session("main")
print(result.snapshot_id, result.summary_generated)

# Fork a session (requires persistence enabled)
fork = await client.fork_session(parent_session_id="main", new_session_id="child-1")
print(fork.child_session_id, fork.parent_session_id)

# Query lineage
children = await client.list_sessions(parent_session_id="main")
for child in children:
    print(child.session_id)

Notes:

• compact_session() works even without persistence (uses an in-memory store).
• fork_session() requires a storage provider (persistence enabled).
• Auto-compaction uses reconstructed context and requires compaction_context_limit to be set.
• For Anthropic sessions with persist_sessions=True and auto_compaction_enabled=True, compaction_context_limit is mandatory (client initialization raises ConfigurationError if missing).

SemVer and Deprecations

• The SDK follows SemVer for public APIs.
• Deprecated APIs emit DeprecationWarning and remain supported for at least two minor releases before removal.
• Use the wormhole_sdk.deprecated helper for new deprecations.

Quickstart

See specs/004-sdk-mvp/quickstart.md for more examples.

Version History

wormhole-sdk follows pre-1.0 SemVer: in 0.x, MINOR bumps mark new release milestones (and breaking changes); PATCH covers fixes within a milestone. Versions are tracked independently of wormhole-core; the wormhole-core dependency range pins to a single core MINOR series.

License

wormhole-sdk is distributed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE for the full text.

The AGPL extends the GNU GPL by requiring that anyone who runs a modified version of the software as a network service must make the source code of that modified version available to the service's users. If you embed wormhole-sdk in a hosted product, that obligation applies to your product as a whole because of the GPL's combined-work rules. For commercial licensing terms outside the AGPL, contact the maintainers.