{"id":491080,"date":"2026-08-16T14:53:19","date_gmt":"2026-08-16T14:53:19","guid":{"rendered":"https:\/\/savepearlharbor.com\/?p=491080"},"modified":"-0001-11-30T00:00:00","modified_gmt":"-0001-11-29T21:00:00","slug":"","status":"publish","type":"post","link":"https:\/\/savepearlharbor.com\/?p=491080","title":{"rendered":"Inside DeepSeek Harness: Cordis, Session Events, Tool Pipelines, and Permission Boundaries"},"content":{"rendered":"<div xmlns=\"http:\/\/www.w3.org\/1999\/xhtml\">\n<p>DeepSeek Harness is often described as an open-source coding agent. <\/p>\n<figure class=\"\"><img decoding=\"async\" src=\"https:\/\/habrastorage.org\/r\/w1560\/getpro\/habr\/\/post_images\/231\/320\/a6e\/231320a6ebe8b6332d16999a55be23ea.png\" sizes=\"(max-width: 780px) 100vw, 50vw\" srcset=\"https:\/\/habrastorage.org\/r\/w780\/getpro\/habr\/\/post_images\/231\/320\/a6e\/231320a6ebe8b6332d16999a55be23ea.png 780w,&#10;       https:\/\/habrastorage.org\/r\/w1560\/getpro\/habr\/\/post_images\/231\/320\/a6e\/231320a6ebe8b6332d16999a55be23ea.png 781w\" loading=\"lazy\" decode=\"async\"\/><\/figure>\n<p>That description is correct, but incomplete.<\/p>\n<p>The more interesting part is its architecture.<\/p>\n<p>DeepSeek Harness is a configurable runtime for constructing agents from model adapters, tools, session services, execution backends, permission policies, interfaces, and agent loops.<\/p>\n<p>Its central design rule is:<\/p>\n<pre><code>Everything is a plugin<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:87px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>This article examines the main technical ideas behind that design.<\/p>\n<h3>System Position<\/h3>\n<p>A language model API normally accepts a list of messages and returns generated content.<\/p>\n<p>A tool-using agent needs a larger runtime:<\/p>\n<pre><code>User interface    \u2193Session management    \u2193Agent loop    \u2193Prompt and tool assembly    \u2193LLM adapter    \u2193Tool-call interpretation    \u2193Permission and sandbox layer    \u2193Filesystem, shell, terminal, subagents<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>DeepSeek Harness provides these layers as a composed application.<\/p>\n<p>It can be used through:<\/p>\n<ul>\n<li>\n<p>A Web profile<\/p>\n<\/li>\n<li>\n<p>A headless profile<\/p>\n<\/li>\n<li>\n<p>A Python SDK<\/p>\n<\/li>\n<li>\n<p>Custom profiles and plugins<\/p>\n<\/li>\n<\/ul>\n<p>The current CLI package also includes dependencies for Bash, PowerShell, filesystem tools, subagents, MCP, jobs, goals, workflows, planning, Web access, and session utilities.<\/p>\n<h3>Cordis as the Composition Layer<\/h3>\n<figure class=\"\"><img decoding=\"async\" src=\"https:\/\/habrastorage.org\/r\/w1560\/getpro\/habr\/\/post_images\/93e\/384\/6d9\/93e3846d996d862d6db9ad47725245d8.png\" sizes=\"(max-width: 780px) 100vw, 50vw\" srcset=\"https:\/\/habrastorage.org\/r\/w780\/getpro\/habr\/\/post_images\/93e\/384\/6d9\/93e3846d996d862d6db9ad47725245d8.png 780w,&#10;       https:\/\/habrastorage.org\/r\/w1560\/getpro\/habr\/\/post_images\/93e\/384\/6d9\/93e3846d996d862d6db9ad47725245d8.png 781w\" loading=\"lazy\" decode=\"async\"\/><\/figure>\n<p>DeepSeek Harness is built on Cordis.<\/p>\n<p>Cordis plugins contribute services, events, and reversible effects to a shared context. In Harness, major subsystems are plugins rather than privileged hard-coded components.<\/p>\n<p>Examples include:<\/p>\n<ul>\n<li>\n<p>LLM adapters<\/p>\n<\/li>\n<li>\n<p>Tool registries<\/p>\n<\/li>\n<li>\n<p>Session persistence<\/p>\n<\/li>\n<li>\n<p>Prompt assembly<\/p>\n<\/li>\n<li>\n<p>Agent loops<\/p>\n<\/li>\n<li>\n<p>Filesystem providers<\/p>\n<\/li>\n<li>\n<p>Shell executors<\/p>\n<\/li>\n<li>\n<p>Sandbox providers<\/p>\n<\/li>\n<li>\n<p>Approval policies<\/p>\n<\/li>\n<li>\n<p>UI integrations<\/p>\n<\/li>\n<\/ul>\n<p>A minimal plugin looks like this:<\/p>\n<pre><code>import type { Context } from \"@deepseek-ai\/cordis\";export const name = \"example-plugin\";export function apply(ctx: Context) {  console.log(\"Plugin loaded\");}<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>A plugin can declare required services:<\/p>\n<pre><code>import type { Context } from \"@deepseek-ai\/cordis\";export const name = \"tool-plugin\";export const inject = [\"tools\"];export function apply(ctx: Context) {  ctx.tools.register(\/* tool definition *\/);}<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>Cordis waits for declared dependencies before loading the plugin.<\/p>\n<p>Registrations made through the context are automatically removed when the plugin unloads. Resources requiring explicit cleanup can use <code>ctx.effect()<\/code> and return a disposer.<\/p>\n<p>This gives the runtime a controlled plugin lifecycle instead of relying on manual global registration.<\/p>\n<h3>Profiles, Bundles, and Patch Layers<\/h3>\n<p>A running Harness instance is composed from a plugin tree.<\/p>\n<p>The main concepts are:<\/p>\n<h4>Profile<\/h4>\n<p>A profile defines the application configuration to boot.<\/p>\n<p>The built-in templates include:<\/p>\n<ul>\n<li>\n<p><code>web<\/code><\/p>\n<\/li>\n<li>\n<p><code>headless<\/code><\/p>\n<\/li>\n<\/ul>\n<p>A profile holds its bundle list, installed external plugins, and its own <code>cordis.patch.yml<\/code>.<\/p>\n<h4>Bundle<\/h4>\n<p>A bundle contains Cordis configuration rows and the code required by those rows.<\/p>\n<p>The base bundle provides core services such as:<\/p>\n<ul>\n<li>\n<p>Model adapters<\/p>\n<\/li>\n<li>\n<p>Tools<\/p>\n<\/li>\n<li>\n<p>Persistence<\/p>\n<\/li>\n<li>\n<p>Sandbox policy<\/p>\n<\/li>\n<li>\n<p>Approval policy<\/p>\n<\/li>\n<li>\n<p>Settings<\/p>\n<\/li>\n<li>\n<p>Credentials<\/p>\n<\/li>\n<li>\n<p>Telemetry<\/p>\n<\/li>\n<\/ul>\n<p>The Web application bundle adds the browser interface.<\/p>\n<p>The headless bundle adds a one-shot non-server runner.<\/p>\n<h4>Patch layers<\/h4>\n<p>Configuration is applied in ordered layers:<\/p>\n<pre><code>Empty root    \u2193Profile bundles, in order    \u2193Profile cordis.patch.yml    \u2193Harness home cordis.patch.yml    \u2193Command-line --patch overlays<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>A patch can replace an existing configuration row by ID or insert a new row.<\/p>\n<p>The effective tree can be inspected with:<\/p>\n<pre><code>dsh --profile web --dump-config<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>This architecture allows local customization without directly modifying the shipped bundles.<\/p>\n<p>Agent Turn and Step Model<\/p>\n<p>DeepSeek Harness distinguishes between a turn and a step.<\/p>\n<p>A step contains:<\/p>\n<p>One model request The tool calls generated by that request The corresponding tool results<\/p>\n<p>A turn may contain zero or more steps.<\/p>\n<p>A simplified flow is:<\/p>\n<pre><code>turn\/start    \u2193Claim user input    \u2193Assemble prompt and tool schemas    \u2193step\/start    \u2193LLM request    \u2193Assistant output    \u2193Tool calls    \u2193Tool execution pipeline    \u2193Tool results    \u2193step\/end    \u2193Continue or stop    \u2193turn\/end<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>DeepSeek\u2019s architecture documentation defines durable events for turn boundaries, step boundaries, user messages, assistant content, tool calls, and tool results. Live agent events are used to observe or intercept work while it is in progress.<\/p>\n<p>This separation gives extension authors several possible interception points.<\/p>\n<p>A plugin can:<\/p>\n<ul>\n<li>\n<p>Rewrite model input<\/p>\n<\/li>\n<li>\n<p>Reject a step<\/p>\n<\/li>\n<li>\n<p>Observe requests<\/p>\n<\/li>\n<li>\n<p>Replace an LLM adapter<\/p>\n<\/li>\n<li>\n<p>Intercept tool execution<\/p>\n<\/li>\n<li>\n<p>Stop a turn<\/p>\n<\/li>\n<li>\n<p>Inject additional context<\/p>\n<\/li>\n<li>\n<p>Add persistent session state<\/p>\n<\/li>\n<\/ul>\n<h3>Event Domains<\/h3>\n<p>The architecture separates events into several domains.<\/p>\n<h4>Session events<\/h4>\n<p>These are durable facts written to the session log.<\/p>\n<p>Examples:<\/p>\n<ul>\n<li>\n<p>User messages<\/p>\n<\/li>\n<li>\n<p>Assistant messages<\/p>\n<\/li>\n<li>\n<p>Tool calls<\/p>\n<\/li>\n<li>\n<p>Tool results<\/p>\n<\/li>\n<li>\n<p>Permission changes<\/p>\n<\/li>\n<li>\n<p>Turn boundaries<\/p>\n<\/li>\n<\/ul>\n<p>Use a session event when the information must survive reload or replay.<\/p>\n<h4>Agent events<\/h4>\n<p>These describe live execution.<\/p>\n<p>Examples include:<\/p>\n<ul>\n<li>\n<p>Pre-step processing<\/p>\n<\/li>\n<li>\n<p>Agent requests<\/p>\n<\/li>\n<li>\n<p>Validation<\/p>\n<\/li>\n<li>\n<p>Continuation<\/p>\n<\/li>\n<li>\n<p>Stopping behavior<\/p>\n<\/li>\n<\/ul>\n<p>These events can observe or modify work in flight.<\/p>\n<h4>Capability events<\/h4>\n<p>These attach behavior to a subsystem seam without requiring the agent loop to import that subsystem directly.<\/p>\n<p>Examples include filesystem, tool, and telemetry events.<\/p>\n<p>This event separation reduces direct coupling between the agent loop and optional capabilities.<\/p>\n<h3>The Session Log as the Source of Model Context<\/h3>\n<p>DeepSeek Harness treats the session log as more than an audit file.<\/p>\n<p>It is the source from which model-visible history is derived.<\/p>\n<p>The architecture follows this rule:<\/p>\n<pre><code>Model-visible means logged<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>Anything that reaches a model request should be reconstructable from the session event stream.<\/p>\n<p>This design supports:<\/p>\n<ul>\n<li>\n<p>Resume<\/p>\n<\/li>\n<li>\n<p>Fork<\/p>\n<\/li>\n<li>\n<p>Replay<\/p>\n<\/li>\n<li>\n<p>Transcripts<\/p>\n<\/li>\n<li>\n<p>Telemetry<\/p>\n<\/li>\n<li>\n<p>Persistence<\/p>\n<\/li>\n<li>\n<p>Debugging<\/p>\n<\/li>\n<\/ul>\n<p>It also creates a useful invariant for agent evaluation.<\/p>\n<p>An evaluator can inspect:<\/p>\n<ul>\n<li>\n<p>Input supplied to the model<\/p>\n<\/li>\n<li>\n<p>Tool schemas<\/p>\n<\/li>\n<li>\n<p>Model responses<\/p>\n<\/li>\n<li>\n<p>Tool requests<\/p>\n<\/li>\n<li>\n<p>Tool results<\/p>\n<\/li>\n<li>\n<p>Stop conditions<\/p>\n<\/li>\n<\/ul>\n<p>This makes the session trajectory suitable for reliability testing and regression analysis.<\/p>\n<h3>Capability Seams<\/h3>\n<p>DeepSeek Harness uses the idea of capability seams.<\/p>\n<p>A complete seam normally contains:<\/p>\n<ol>\n<li>\n<p>A service definition<\/p>\n<\/li>\n<li>\n<p>A service provider<\/p>\n<\/li>\n<li>\n<p>A consumer<\/p>\n<\/li>\n<\/ol>\n<p>For example, filesystem access may include:<\/p>\n<ul>\n<li>\n<p>A filesystem interface<\/p>\n<\/li>\n<li>\n<p>A local or remote implementation<\/p>\n<\/li>\n<li>\n<p>Model-facing tools that consume it<\/p>\n<\/li>\n<\/ul>\n<p>The same model-facing tool could continue to work when the provider changes from local execution to a remote sandbox.<\/p>\n<p>The architecture applies this approach to:<\/p>\n<ul>\n<li>\n<p>Filesystems<\/p>\n<\/li>\n<li>\n<p>Shell execution<\/p>\n<\/li>\n<li>\n<p>Terminals<\/p>\n<\/li>\n<li>\n<p>Sandboxes<\/p>\n<\/li>\n<li>\n<p>Subagents<\/p>\n<\/li>\n<li>\n<p>LLM providers<\/p>\n<\/li>\n<li>\n<p>Persistent jobs<\/p>\n<\/li>\n<\/ul>\n<p>This is useful because the agent loop does not need custom branches for every deployment.<\/p>\n<p>A provider swap can change the execution environment while preserving the higher-level tool interface.<\/p>\n<h3>DeepSeek Model Adapter<\/h3>\n<p>The official DeepSeek adapter registers the provider route:<\/p>\n<pre><code>deepseek-official<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>Its default model catalog includes:<\/p>\n<pre><code>deepseek-v4-flashdeepseek-v4-pro<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>The adapter supports:<\/p>\n<ul>\n<li>\n<p>Streaming responses<\/p>\n<\/li>\n<li>\n<p>Tool-call translation<\/p>\n<\/li>\n<li>\n<p>Thinking control<\/p>\n<\/li>\n<li>\n<p>Reasoning effort<\/p>\n<\/li>\n<li>\n<p>Retry metadata<\/p>\n<\/li>\n<li>\n<p>Context-window information<\/p>\n<\/li>\n<li>\n<p>Cache-read usage<\/p>\n<\/li>\n<li>\n<p>Structured error mapping<\/p>\n<\/li>\n<li>\n<p>Dynamic settings<\/p>\n<\/li>\n<li>\n<p>Per-request credential resolution<\/p>\n<\/li>\n<\/ul>\n<p>The default advertised context window is one million tokens for the two V4 models.<\/p>\n<p>The adapter re-reads dynamic settings and credentials for each operation. This allows a changed API key or endpoint to take effect on the next request without restarting the whole application.<\/p>\n<p>The credential is resolved through the Harness credential service or an environment variable. Literal keys are not stored directly in the model configuration block.<\/p>\n<h3>Tool Execution Pipeline<\/h3>\n<p>A model tool call does not execute immediately.<\/p>\n<p>It passes through a guarded tool pipeline:<\/p>\n<pre><code>Model tool call    \u2193tools\/pre-execute    \u2193Permission and policy handling    \u2193tools\/execute    \u2193Provider implementation    \u2193tools\/post-execute    \u2193Durable tool result<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>The architecture exposes pre-execution and post-execution extension points.<\/p>\n<p>A plugin could use these points to:<\/p>\n<ul>\n<li>\n<p>Validate tool arguments<\/p>\n<\/li>\n<li>\n<p>Add logging<\/p>\n<\/li>\n<li>\n<p>Reject unsafe requests<\/p>\n<\/li>\n<li>\n<p>Apply company policy<\/p>\n<\/li>\n<li>\n<p>Measure execution time<\/p>\n<\/li>\n<li>\n<p>Redact sensitive output<\/p>\n<\/li>\n<li>\n<p>Add verification<\/p>\n<\/li>\n<li>\n<p>Transform results<\/p>\n<\/li>\n<\/ul>\n<p>This is a more scalable approach than embedding all policy inside each individual tool.<\/p>\n<h3>Sandbox and Approval Are Independent<\/h3>\n<p>DeepSeek Harness models sandboxing and approval as two separate controls.<\/p>\n<p>The default permission presets include:<\/p>\n<pre><code>workspace-write:  sandbox: workspace-write  approval: askdanger-full-access:  sandbox: danger-full-access  approval: never<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>The preset is a user-facing bundle, but enforcement remains inside the underlying sandbox and approval services.<\/p>\n<p>This distinction is important.<\/p>\n<p>Approval answers:<\/p>\n<blockquote>\n<p>Must the user confirm this action?<\/p>\n<\/blockquote>\n<p>Sandboxing answers:<\/p>\n<blockquote>\n<p>What resources can the action reach?<\/p>\n<\/blockquote>\n<p>An approval dialog is not a filesystem boundary.<\/p>\n<p>A sandbox is not a substitute for user intent.<\/p>\n<p>Production systems should evaluate both.<\/p>\n<h3>Web, Headless, and Python Interfaces<\/h3>\n<p>The Web UI starts with:<\/p>\n<pre><code>npx @deepseek-ai\/dsh web<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>It normally listens on:<\/p>\n<pre><code>http:\/\/127.0.0.1:3080<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>After startup, the user configures a model, selects a workspace, creates a session, and submits a task.<\/p>\n<p>The headless profile runs a persisted one-shot task:<\/p>\n<pre><code>dsh --profile headless \"inspect the repository and run tests\"<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>The CLI also supports plugin management and profile-specific patch layers.<\/p>\n<p>The Python SDK provides a programmatic interface around a bundled runtime:<\/p>\n<pre><code>from deepseek_harness import DeepSeekHarnesswith DeepSeekHarness(    provider=\"deepseek-official\",    model=\"deepseek-v4-flash\",    cwd=\"\/path\/to\/workspace\",    session_root=\"\/path\/to\/sessions\",    cordis=\"\/path\/to\/config.yml\",) as harness:    result = harness.run(        \"Inspect the repository and fix the failing tests.\",        session_id=\"example-001\",    )print(result.final_response)<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>A reused session ID can preserve both conversation state and the session-owned shell process.<\/p>\n<h3>Current Limitations<\/h3>\n<p>The repository explicitly marks DeepSeek Harness as a developer preview and warns that compatibility-breaking changes will occur.<\/p>\n<p>At the time of writing, the CLI package is still published as a release candidate.<\/p>\n<p>Potential adoption risks include:<\/p>\n<ul>\n<li>\n<p>Changing configuration formats<\/p>\n<\/li>\n<li>\n<p>Plugin API changes<\/p>\n<\/li>\n<li>\n<p>Incomplete documentation<\/p>\n<\/li>\n<li>\n<p>Provider compatibility differences<\/p>\n<\/li>\n<li>\n<p>Security assumptions that vary by operating system<\/p>\n<\/li>\n<li>\n<p>Limited operational history<\/p>\n<\/li>\n<li>\n<p>Unstable third-party plugin ecosystem<\/p>\n<\/li>\n<\/ul>\n<p>The Python minimal example also warns that its <code>danger-full-access<\/code> configuration can modify any path available to the runtime process and should be used only inside a disposable checkout or container.<\/p>\n<h3>Conclusion<\/h3>\n<p>DeepSeek Harness is technically interesting because it treats the agent runtime as a composable system rather than a fixed application.<\/p>\n<\/div>\n<p>\u0441\u0441\u044b\u043b\u043a\u0430 \u043d\u0430 \u043e\u0440\u0438\u0433\u0438\u043d\u0430\u043b \u0441\u0442\u0430\u0442\u044c\u0438 <a href=\"https:\/\/habr.com\/ru\/articles\/1070958\/\">https:\/\/habr.com\/ru\/articles\/1070958\/<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<p>DeepSeek Harness is often described as an open-source coding agent. That description is correct, but incomplete.The more interesting part is its architecture.DeepSeek Harness is a configurable runtime for constructing agents from model adapters, tools, session services, execution backends, permission policies, interfaces, and agent loops.Its central design rule is:Everything is a pluginThis article examines the main technical ideas behind that design.System PositionA language model API normally accepts a list of messages and returns generated content.A tool-using agent needs a larger runtime:User interface    \u2193Session management    \u2193Agent loop    \u2193Prompt and tool assembly    \u2193LLM adapter    \u2193Tool-call interpretation    \u2193Permission and sandbox layer    \u2193Filesystem, shell, terminal, subagentsDeepSeek Harness provides these layers as a composed application.It can be used through:A Web profileA headless profileA Python SDKCustom profiles and pluginsThe current CLI package also includes dependencies for Bash, PowerShell, filesystem tools, subagents, MCP, jobs, goals, workflows, planning, Web access, and session utilities.Cordis as the Composition LayerDeepSeek Harness is built on Cordis.Cordis plugins contribute services, events, and reversible effects to a shared context. In Harness, major subsystems are plugins rather than privileged hard-coded components.Examples include:LLM adaptersTool registriesSession persistencePrompt assemblyAgent loopsFilesystem providersShell executorsSandbox providersApproval policiesUI integrationsA minimal plugin looks like this:import type { Context } from &#171;@deepseek-ai\/cordis&#187;;export const name = &#171;example-plugin&#187;;export function apply(ctx: Context) {  console.log(&#171;Plugin loaded&#187;);}A plugin can declare required services:import type { Context } from &#171;@deepseek-ai\/cordis&#187;;export const name = &#171;tool-plugin&#187;;export const inject = [&#171;tools&#187;];export function apply(ctx: Context) {  ctx.tools.register(\/* tool definition *\/);}Cordis waits for declared dependencies before loading the plugin.Registrations made through the context are automatically removed when the plugin unloads. Resources requiring explicit cleanup can use ctx.effect() and return a disposer.This gives the runtime a controlled plugin lifecycle instead of relying on manual global registration.Profiles, Bundles, and Patch LayersA running Harness instance is composed from a plugin tree.The main concepts are:ProfileA profile defines the application configuration to boot.The built-in templates include:webheadlessA profile holds its bundle list, installed external plugins, and its own cordis.patch.yml.BundleA bundle contains Cordis configuration rows and the code required by those rows.The base bundle provides core services such as:Model adaptersToolsPersistenceSandbox policyApproval policySettingsCredentialsTelemetryThe Web application bundle adds the browser interface.The headless bundle adds a one-shot non-server runner.Patch layersConfiguration is applied in ordered layers:Empty root    \u2193Profile bundles, in order    \u2193Profile cordis.patch.yml    \u2193Harness home cordis.patch.yml    \u2193Command-line &#8212;patch overlaysA patch can replace an existing configuration row by ID or insert a new row.The effective tree can be inspected with:dsh &#8212;profile web &#8212;dump-configThis architecture allows local customization without directly modifying the shipped bundles.Agent Turn and Step ModelDeepSeek Harness distinguishes between a turn and a step.A step contains:One model request The tool calls generated by that request The corresponding tool resultsA turn may contain zero or more steps.A simplified flow is:turn\/start    \u2193Claim user input    \u2193Assemble prompt and tool schemas    \u2193step\/start    \u2193LLM request    \u2193Assistant output    \u2193Tool calls    \u2193Tool execution pipeline    \u2193Tool results    \u2193step\/end    \u2193Continue or stop    \u2193turn\/endDeepSeek\u2019s architecture documentation defines durable events for turn boundaries, step boundaries, user messages, assistant content, tool calls, and tool results. Live agent events are used to observe or intercept work while it is in progress.This separation gives extension authors several possible interception points.A plugin can:Rewrite model inputReject a stepObserve requestsReplace an LLM adapterIntercept tool executionStop a turnInject additional contextAdd persistent session stateEvent DomainsThe architecture separates events into several domains.Session eventsThese are durable facts written to the session log.Examples:User messagesAssistant messagesTool callsTool resultsPermission changesTurn boundariesUse a session event when the information must survive reload or replay.Agent eventsThese describe live execution.Examples include:Pre-step processingAgent requestsValidationContinuationStopping behaviorThese events can observe or modify work in flight.Capability eventsThese attach behavior to a subsystem seam without requiring the agent loop to import that subsystem directly.Examples include filesystem, tool, and telemetry events.This event separation reduces direct coupling between the agent loop and optional capabilities.The Session Log as the Source of Model ContextDeepSeek Harness treats the session log as more than an audit file.It is the source from which model-visible history is derived.The architecture follows this rule:Model-visible means loggedAnything that reaches a model request should be reconstructable from the session event stream.This design supports:ResumeForkReplayTranscriptsTelemetryPersistenceDebuggingIt also creates a useful invariant for agent evaluation.An evaluator can inspect:Input supplied to the modelTool schemasModel responsesTool requestsTool resultsStop conditionsThis makes the session trajectory suitable for reliability testing and regression analysis.Capability SeamsDeepSeek Harness uses the idea of capability seams.A complete seam normally contains:A service definitionA service providerA consumerFor example, filesystem access may include:A filesystem interfaceA local or remote implementationModel-facing tools that consume itThe same model-facing tool could continue to work when the provider changes from local execution to a remote sandbox.The architecture applies this approach to:FilesystemsShell executionTerminalsSandboxesSubagentsLLM providersPersistent jobsThis is useful because the agent loop does not need custom branches for every deployment.A provider swap can change the execution environment while preserving the higher-level tool interface.DeepSeek Model AdapterThe official DeepSeek adapter registers the provider route:deepseek-officialIts default model catalog includes:deepseek-v4-flashdeepseek-v4-proThe adapter supports:Streaming responsesTool-call translationThinking controlReasoning effortRetry metadataContext-window informationCache-read usageStructured error mappingDynamic settingsPer-request credential resolutionThe default advertised context window is one million tokens for the two V4 models.The adapter re-reads dynamic settings and credentials for each operation. This allows a changed API key or endpoint to take effect on the next request without restarting the whole application.The credential is resolved through the Harness credential service or an environment variable. Literal keys are not stored directly in the model configuration block.Tool Execution PipelineA model tool call does not execute immediately.It passes through a guarded tool pipeline:Model tool call    \u2193tools\/pre-execute    \u2193Permission and policy handling    \u2193tools\/execute    \u2193Provider implementation    \u2193tools\/post-execute    \u2193Durable tool resultThe architecture exposes pre-execution and post-execution extension points.A plugin could use these points to:Validate tool argumentsAdd loggingReject unsafe requestsApply company policyMeasure execution timeRedact sensitive outputAdd verificationTransform resultsThis is a more scalable approach than embedding all policy inside each individual tool.Sandbox and Approval Are IndependentDeepSeek Harness models sandboxing and approval as two separate controls.The default permission presets include:workspace-write:  sandbox: workspace-write  approval: askdanger-full-access:  sandbox: danger-full-access  approval: neverThe preset is a user-facing bundle, but enforcement remains inside the underlying sandbox and approval services.This distinction is important.Approval answers:Must the user confirm this action?Sandboxing answers:What resources can the action reach?An approval dialog is not a filesystem boundary.A sandbox is not a substitute for user intent.Production systems should evaluate both.Web, Headless, and Python InterfacesThe Web UI starts with:npx @deepseek-ai\/dsh webIt normally listens on:http:\/\/127.0.0.1:3080After startup, the user configures a model, selects a workspace, creates a session, and submits a task.The headless profile runs a persisted one-shot task:dsh &#8212;profile headless &#171;inspect the repository and run tests&#187;The CLI also supports plugin management and profile-specific patch layers.The Python SDK provides a programmatic interface around a bundled runtime:from deepseek_harness import DeepSeekHarnesswith DeepSeekHarness(    provider=&#187;deepseek-official&#187;,    model=&#187;deepseek-v4-flash&#187;,    cwd=&#187;\/path\/to\/workspace&#187;,    session_root=&#187;\/path\/to\/sessions&#187;,    cordis=&#187;\/path\/to\/config.yml&#187;,) as harness:    result = harness.run(        &#171;Inspect the repository and fix the failing tests.&#187;,        session_id=&#187;example-001&#8243;,    )print(result.final_response)A reused session ID can preserve both conversation state and the session-owned shell process.Current LimitationsThe repository explicitly marks DeepSeek Harness as a developer preview and warns that compatibility-breaking changes will occur.At the time of writing, the CLI package is still published as a release candidate.Potential adoption risks include:Changing configuration formatsPlugin API changesIncomplete documentationProvider compatibility differencesSecurity assumptions that vary by operating systemLimited&#8230;<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[],"tags":[],"class_list":["post-491080","post","type-post","status-publish","format-standard","hentry"],"_links":{"self":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/posts\/491080","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=491080"}],"version-history":[{"count":0,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/posts\/491080\/revisions"}],"wp:attachment":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=491080"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=491080"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=491080"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}