description	kind
The composable persona row presets mount to give one agent its own system-prompt persona, for users and maintainers configuring or debugging it.	package-reference

@deepseek-ai/dsh-persona

English | 中文

Summary

dsh-persona gives one agent its own persona: a preset mounts this composable row to register the deployment:persona system-prompt section, shadowing the deployment-wide persona for that session. It can also make that persona the session's complete system prompt, suppressing every other section, and can turn off dynamic runtime-context snapshots for the session. Mount it inside a preset composition — mounting it globally collides with the prompt registry's own persona registration and fails loud. Without this row, a preset could change an agent's tools but never its identity.

Use this package
Understand the implementation
Further Exploration
Model Experience
Known Limitations and Deferred Work
Dev Note

Use this package

Mount this row inside a preset composition to give that preset's sessions their own persona. The row needs an agent scope: mounted outside one it collides with the prompt registry's own deployment:persona registration and fails loud — the deployment persona already has an owner, and the whole point of this row is to shadow it for one agent.

Configuration

- name: '@deepseek-ai/dsh-persona'
  config:
    text: You are a terse systems engineer who answers in short commands.

Field	Default	Meaning
`text`	required	Persona prose rendered as the `deployment:persona` section
`complete`	`false`	Restore this persona after assembly as the only system-prompt section
`includeRuntimeContext`	`true`	Include dynamic runtime-context snapshots for this agent scope; false suppresses every context contribution without disabling its owning services

The generated configuration catalog is the exhaustive source for every accepted field and its JSDoc.

Persona behavior

The persona text is a template: complete {{…}} groups resolve strictly against registered prompt variables when the prompt renders, not when it assembles. Empty text still occupies the slot — it shadows the deployment persona away entirely, then disappears at render. With complete: true, assembly still resolves contexts, tools, variables, and cooperative listeners, but the prompt registry restores this exact persona as the sole section; no identity, tool guidance, or listener can append prompt text. With includeRuntimeContext: false, context providers are not evaluated for this scope and contexts added by assembly listeners are discarded.

When to use it

Use this row when a preset must change an agent's identity and not only its tools. The deployment-wide persona itself is configured on the dsh-system-prompt row, not here; this row exists only to shadow or replace it for one agent.

Understand the implementation

Implementation internals — click to expand

How the row registers

apply registers one prompt section through ctx.systemPrompt.section({ name: PERSONA_SECTION, order: PERSONA_ORDER, text, complete? }) inside the mounting context's scope, so the section lands at order 0 — immediately after the harness identity opener — and only for agents joined to the preset. PERSONA_SECTION and PERSONA_ORDER are imported from dsh-system-prompt rather than restated, so a preset persona always shadows the deployment's instead of landing beside it. includeRuntimeContext: false calls ctx.systemPrompt.suppressRuntimeContext().

Why the row is scope-only

dsh-system-prompt owns the global persona as its own config and registers deployment:persona unconditionally, so a process has exactly one. This row collides with that registration outside an agent scope, by design: the row exists because a preset cannot mount the prompt registry itself.

Source map

File	Role
`src/index.ts`	Plugin entry: `Config` schema, persona section registration, runtime-context suppression
`src/invariant.ts`	Invariant companion (no runtime invariant; the prompt registry owns identity, complete-prompt enforcement, and disposal)

Further Exploration

Read these pages when the package-level contract is not enough; they move from the preset composition to the prompt registry this row feeds.

agent-presets package — the preset composition this row mounts into.
System prompt subsystem — sections, assembly, and the persona slot this row shadows.
Generated configuration catalog — every accepted config field and its source declaration.

Model Experience

The persona section

What the model sees

The deployment:persona section at order 0, immediately after the harness identity opener, carrying exactly this row's configured text with prompt variables resolved. For an agent whose preset mounts this row, it replaces whatever persona the deployment configured. In complete mode, the model sees only this rendered section as its system prompt. Runtime context remains enabled by default; when disabled, a fresh agent receives no runtime-context snapshot from sandbox policy, approval policy, delegation, or another system-prompt context provider.

Token effect

Fixed for a given preset: the persona's own tokens on every request that agent makes, and none for any other agent. Empty text contributes nothing. Complete mode removes every other system-prompt token for that agent.

KV Cache effect

Prefix-stable for the life of an agent — the row mounts once, before the agent is published and therefore before its first request, and its text never changes while the agent runs. Two agents on different presets establish different prefixes from this section onward; neither can invalidate the other's reuse.

Known Limitations and Deferred Work

These limits define when the row is a poor fit. They are current package constraints, not a task backlog.

No global mount — the prompt registry owns the unscoped persona slot, so this row is usable only from a scoped composition. A deployment-wide persona change belongs in the system-prompt row's own config.
Runtime-context suppression is all-or-nothing — includeRuntimeContext: false turns off every context contribution for the scope, including sandbox policy, approval policy, and delegation; there is no per-provider filter.

Dev Note

Working context for maintainers — click to expand

None.

README.md