Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.
Python agentagentic-aiagentic-frameworkagentic-workflowaiautomationclaudedeepseekgenaigptllmlow-codemcpnextjsno-codeopenaipythonskillsworkflow
import type { Descriptor, OpFacets } from './describe'
import type { ExitCodeValue } from '@/errors/codes'
import type { CommandContext } from '@/plugins/base'
import type { Example, JsonSchema } from '@/plugins/catalog'
import type { Printable } from '@/sys/io/view'
import { z } from 'zod'
import { validateInput } from '@/call/validate'
import { BaseError, LOC_SEPARATOR } from '@/errors/base'
import { ErrorCode } from '@/errors/codes'
import { inputSchema } from '@/plugins/argv/parse'
import { COMMAND_SEPARATOR } from '@/protocol/op-id'
import { typedName } from '@/util/flag-name'
import { BINARY } from '@/version/info'
import { commandRow } from './describe'
export type { Descriptor, OpFacets } from './describe'
export const COMMAND_EFFECTS = ['read', 'write', 'destructive'] as const
export type CommandEffect = (typeof COMMAND_EFFECTS)[number]
export function isCommandEffect(value: string): value is CommandEffect {
return (COMMAND_EFFECTS as readonly string[]).includes(value)
}
export const HELP_WORD = 'help'
/** Points at the help for `words`, or at the map when nothing is named. */
export function helpHint(...words: readonly string[]): string {
return ['run', BINARY, HELP_WORD, ...words].join(COMMAND_SEPARATOR)
}
type InputCheck = Readonly<{
command: readonly string[]
schema: JsonSchema
positional?: readonly string[]
input: Record<string, unknown>
}>
function typedField(loc: readonly (string | number)[], positional: readonly string[] = []) {
const [head, ...rest] = loc
if (typeof head !== 'string') return undefined
return [typedName(head, positional), ...rest].join(LOC_SEPARATOR)
}
export function assertValidInput(check: InputCheck): void {
const details = validateInput(check.schema, check.input)
if (details.length === 0) return
throw new BaseError({
code: ErrorCode.InputInvalid,
message: `invalid input for "${check.command.join(COMMAND_SEPARATOR)}"`,
hint: helpHint(...check.command),
details: details.map((detail) => ({
...detail,
field: typedField(detail.loc, check.positional),
})),
schema: check.schema,
})
}
/** Returned by a command that already wrote its output or needs a non-zero exit. */
export class Outcome {
readonly code: ExitCodeValue
readonly body?: Printable
constructor(code: ExitCodeValue, body?: Printable) {
this.code = code
this.body = body
}
}
export type CommandResult = Printable | Outcome | undefined
export type HelpArgs = {
readonly path: readonly string[]
readonly rest: readonly string[]
readonly ctx: CommandContext
}
export abstract class Command<S extends z.ZodObject = z.ZodObject> {
static summary = ''
static effect: CommandEffect | undefined = 'read'
static input: z.ZodObject = z.object({})
static positional: readonly string[] = []
static examples: readonly Example[] = []
static hidden?: boolean
static schema(this: CommandConstructor): JsonSchema {
return inputSchema(this.input)
}
static flags(this: CommandConstructor): JsonSchema {
return this.schema()
}
static facets(): Partial<OpFacets> {
return {}
}
// The one input gate. parseArgv only coerces what was typed; zod owns the declared
// defaults, so reaching its parse means a zod rejection is a schema/parser contract bug.
static finalize(
this: CommandConstructor,
input: Record<string, unknown>,
path: readonly string[],
): Record<string, unknown> {
assertValidInput({ command: path, schema: this.schema(), positional: this.positional, input })
const parsed = this.input.safeParse(input)
if (!parsed.success) {
throw new BaseError({
code: ErrorCode.Unknown,
message: parsed.error.issues.map((issue) => issue.message).join('; '),
cause: parsed.error,
})
}
return parsed.data
}
static async help(this: CommandConstructor, args: HelpArgs): Promise<Descriptor> {
return { ...commandRow(this, args.path), ...this.facets() }
}
abstract run(input: z.infer<S>, ctx: CommandContext): Promise<CommandResult>
}
// `Omit` drops the abstract construct signature (and the generic `S` with it), so the
// registry can hold and instantiate any concrete subclass while keeping the statics.
export type CommandConstructor = Omit<typeof Command, 'prototype'> & (new () => Command)