7.1 KiB
description, kind
| 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.
Table of Contents
- 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-promptrow's own config. - Runtime-context suppression is all-or-nothing —
includeRuntimeContext: falseturns 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.