Files
deepseek-harness/packages/subagent/subagent/src/catalog.ts
T

165 lines
6.2 KiB
TypeScript

/**
* Parent-owned durable subagent catalog events and their chunked projection.
*
* @module @deepseek-ai/dsh-subagent/catalog
*/
import { z } from 'zod'
import { appendChunkedList, chunkedListSchema, iterateChunkedList } from '@deepseek-ai/dsh-chunked-list'
import type { ChunkedList } from '@deepseek-ai/dsh-chunked-list'
import type {
Session,
SessionEvent,
SessionHeader,
SessionId,
SessionLogOffset,
} from '@deepseek-ai/dsh-session'
import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
import type { SubagentCatalogEntry } from './projection-types.ts'
/** Catalog payload version emitted by local child creation. */
export const SUBAGENT_CATALOG_VERSION = 0
type KnownCatalogMode =
| { readonly mode: 'one-shot'; readonly label?: string }
| { readonly mode: 'continuable'; readonly label: string }
/** Parent catalog v0 records local modes, v1 adds unknown children, and v2 records external executions. */
export type SubagentCatalogEvent =
& {
readonly childId: SessionId
readonly childCreatedAt: number
} & (
| ({ readonly version: 0 } & KnownCatalogMode)
| ({ readonly version: 1 } & (KnownCatalogMode | { readonly mode: 'unknown'; readonly label?: string }))
| { readonly version: 2; readonly mode: 'external'; readonly label?: string }
)
declare module '@deepseek-ai/dsh-session/types' {
interface SessionEventMap {
/**
* A direct child's identity and available discovery fields.
* @param data - versioned parent-owned catalog entry.
*/
'subagent/catalog': SubagentCatalogEvent
}
}
/** Host fold state for one parent catalog. */
export interface SubagentCatalogState {
readonly inheritedEventCount: SessionLogOffset
readonly head?: ChunkedList<SubagentCatalogEvent> | undefined
}
const sessionIdSchema = z.string() as unknown as z.ZodType<SessionId>
const oneShotCatalogSchema = z.object({
version: z.union([z.literal(0), z.literal(1)]),
childId: sessionIdSchema,
childCreatedAt: z.number().int().nonnegative(),
mode: z.literal('one-shot'),
label: z.string().optional(),
}).strict()
const continuableCatalogSchema = z.object({
version: z.union([z.literal(0), z.literal(1)]),
childId: sessionIdSchema,
childCreatedAt: z.number().int().nonnegative(),
mode: z.literal('continuable'),
label: z.string(),
}).strict()
const externalCatalogSchema = oneShotCatalogSchema.extend({ version: z.literal(2), mode: z.literal('external') })
const unknownCatalogSchema = oneShotCatalogSchema.extend({ version: z.literal(1), mode: z.literal('unknown') })
const eventDataSchema = z.union([
oneShotCatalogSchema,
externalCatalogSchema,
continuableCatalogSchema,
unknownCatalogSchema,
]) as z.ZodType<SubagentCatalogEvent>
const viewSchema = z.array(z.union([
oneShotCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
id: sessionIdSchema,
createdAt: oneShotCatalogSchema.shape.childCreatedAt,
}),
externalCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
id: sessionIdSchema,
createdAt: externalCatalogSchema.shape.childCreatedAt,
}),
continuableCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
id: sessionIdSchema,
createdAt: continuableCatalogSchema.shape.childCreatedAt,
}),
unknownCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
id: sessionIdSchema,
createdAt: unknownCatalogSchema.shape.childCreatedAt,
}),
])) as z.ZodType<SubagentCatalogEntry[]>
const stateSchema: z.ZodType<SubagentCatalogState> = z.object({
inheritedEventCount: z.number().int().nonnegative() as unknown as z.ZodType<SessionLogOffset>,
head: chunkedListSchema(eventDataSchema).optional(),
}).strict()
/**
* Materialize complete and unknown-mode child identities from parent catalog events.
* @param state - parent catalog fold state.
* @returns current direct-child rows in parent catalog event order.
*/
function subagentCatalogEntries(state: SubagentCatalogState): SubagentCatalogEntry[] {
const entries: SubagentCatalogEntry[] = []
for (const data of iterateChunkedList(state.head)) {
const { version: _version, childId, childCreatedAt, ...descriptor } = data
entries.push({ id: childId, createdAt: childCreatedAt, ...descriptor })
}
return entries
}
/** Parent-owned direct-child catalog projection; invalid own facts reject restoration. */
export const subagentCatalogProjectionDefinition = {
key: 'subagentCatalog',
stateSchema,
init: (_header: SessionHeader, inheritedEventCount: SessionLogOffset) => ({ inheritedEventCount }),
apply: (state, event: SessionEvent) => {
if (event.type !== 'subagent/catalog' || event.seq < state.inheritedEventCount) return state
return { ...state, head: appendChunkedList(state.head, eventDataSchema.parse(event.data)) }
},
stateVersion: 6,
wire: { viewSchema, view: subagentCatalogEntries },
} satisfies ProjectionDefinition<'subagentCatalog', SubagentCatalogState>
/**
* Append a complete direct-child discovery fact to its parent Session.
* @param parent - durable direct parent receiving the discovery fact.
* @param child - established child's immutable Session metadata.
* @param descriptor - mode-discriminated creation label frozen with the child.
*/
export function establishCatalogChild(
parent: Session,
child: SessionHeader,
descriptor: { readonly mode: 'continuable'; readonly label: string },
): void {
parent.append('subagent/catalog', {
version: SUBAGENT_CATALOG_VERSION,
childId: child.id,
childCreatedAt: child.createdAt,
mode: descriptor.mode,
label: descriptor.label,
})
}
/** Catalog payload version emitted by external execution creation. */
const EXTERNAL_SUBAGENT_CATALOG_VERSION = 2
/**
* Record an external execution without a local child Session.
* @param parent - durable direct parent receiving the discovery fact.
* @param childId - identity returned by the external provider.
* @param label - display label assigned by the caller.
*/
export function establishExternalCatalogChild(parent: Session, childId: SessionId, label: string): void {
parent.append('subagent/catalog', {
version: EXTERNAL_SUBAGENT_CATALOG_VERSION,
childId,
childCreatedAt: Date.now(),
mode: 'external',
label,
})
}