Domain imports
Agent-owned approval contracts live in
harnest.agent.approval. Other existing
domain modules include harnest.content, harnest.credentials,
harnest.continuation, harnest.extensions, harnest.skills, harnest.task,
harnest.logging, and harnest.tracing.
AgentResponse from harnest.http represents an HTTP route response. AgentResponse from harnest.context represents a local agent invocation response; select the contract for your integration.
The implementation path harnest.context_agent has been removed. Use from harnest import context for context.agent operations and from harnest.context import AgentSession, AgentResponse for their contracts. Modules prefixed with _ are private implementation details.
The harnest.task_storage implementation path has also been removed. Import TaskRecord, TaskStore, and TaskStoreConflictError from harnest.task. Run harnest upgrade AGENT_DIR --apply to rewrite supported imports in an existing project. Imports or uses of private storage helpers require manual review.
IDE autocomplete and hover help
Synchronize the managed environment to enable typed completion and hover documentation:python.defaultInterpreterPath in .vscode/settings.json to the environment it synchronized. For the default runtime profile on macOS or Linux:
Scripts/python.exe; development and eval profiles select the eval directory. Sync replaces stale interpreter settings while preserving comments and unrelated preferences, even when a user-owned .venv prevents creating the convenience link. Open the agent folder as your VS Code workspace folder so these settings apply.
After a dependency change during development reload, run harnest env sync . again to refresh an editor setting that points to the old interpreter. A Harnest-managed .venv link follows the replacement automatically for the selected profile.
VS Code can retain a previously selected interpreter separately from this setting. If it still uses another interpreter, run Python: Select Interpreter and choose the exact path printed by sync. See the VS Code settings reference. Other IDEs can use the same interpreter.
Codex desktop, Codex CLI, and Antigravity 2.0 are separate agent applications.
For Python commands in these agents, use .venv/bin/python directly; their
terminal commands do not inherit the VS Code Python interpreter setting.
Harnest preserves any .venv it does not own and prints the managed interpreter for manual selection. Keep .venv out of version control.
Harnest includes static declarations for its lazy domain namespaces and invocation context. Editors can discover methods and signatures on harnest.context, context.agent, context.session, context.mcp, context.skills, and the other context capabilities without running an agent. Context values still resolve for each active invocation; do not access them at module import time.
Core functions and methods carry parameter and return annotations. Static consumer checks cover public classes, inherited methods, properties, and protocol methods across Harnest’s domains. Task, context-provider, and lifecycle decorators preserve the authored callable’s parameters and result type, so an editor can flag invalid direct calls:
str argument and result types. Deferred task arguments are validated at runtime; .defer() accepts scheduling options and returns a TaskHandle. Dynamic payloads and resource lookups without an expected class may still use Any.
For application-defined resources, pass the expected class to preserve its completion and return type:
CustomerDirectory. context.storage("name", ExpectedType) and context.extensions("name", ExpectedContext) also preserve the supplied type. Lookups without an expected type return Any; Harnest cannot infer a company’s resource type from a runtime string. Runtime type validation remains in place.
The managed wheel also includes editor-only definitions for
harnest.extensions.docker and harnest.extensions.hatchet. Those imports get
completion and hover help while the actual modules remain available at runtime
only when their corresponding official extension is installed in the project.
Run env sync after dependency changes. Harnest reuses a stable environment path,
so the .venv link continues to resolve the current interpreter. Synchronization
also migrates Harnest-owned links away from older fingerprinted environments.
Scoped operations
Sandbox execution and cleanup share a namespace:control.current() returns the active scope. See sandbox failure recovery and cleanup for cancellation and deadline guarantees.
Query lifecycle coverage with the same domain pattern:
Public API stability
Public module exports, annotations, and docstrings are checked by the release gate. Re-exports preserve object identity, including exception classes. During0.x, Harnest may make a breaking public Python API change only in a
minor release. Public names and signatures are otherwise backward compatible;
deprecated APIs remain available for at least one minor release before removal,
except when retaining them would preserve a security defect. Patch releases do
not intentionally break these contracts.
Serialized plans, locks, manifests, and HTTP documents have independent format versions.