Skip to content

Commit 3228241

Browse files
steipetesteipete
committed
docs: document schema status helpers
1 parent 3eaab86 commit 3228241

4 files changed

Lines changed: 41 additions & 0 deletions

File tree

‎src/agents/image-generation-task-status.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
/**
2+
* Image generation task status helpers.
3+
*
4+
* These wrap the shared media task status helpers with image-specific task kind,
5+
* source id, duplicate-guard timing, and prompt/status wording.
6+
*/
17
import type { TaskRecord } from "../tasks/task-registry.types.js";
28
import {
39
buildActiveMediaGenerationTaskPromptContextForSession,
@@ -16,17 +22,20 @@ export const IMAGE_GENERATION_TASK_KIND = "image_generation";
1622
const IMAGE_GENERATION_SOURCE_PREFIX = "image_generate";
1723
const RECENT_IMAGE_GENERATION_DUPLICATE_GUARD_MS = 2 * 60_000;
1824

25+
/** Returns whether a task is an active image generation task. */
1926
export function isActiveImageGenerationTask(task: TaskRecord): boolean {
2027
return isActiveMediaGenerationTask({
2128
task,
2229
taskKind: IMAGE_GENERATION_TASK_KIND,
2330
});
2431
}
2532

33+
/** Extracts the provider id from an image generation task source. */
2634
export function getImageGenerationTaskProviderId(task: TaskRecord): string | undefined {
2735
return getMediaGenerationTaskProviderId(task, IMAGE_GENERATION_SOURCE_PREFIX);
2836
}
2937

38+
/** Finds the active image generation task for a session and optional prompt. */
3039
export function findActiveImageGenerationTaskForSession(
3140
sessionKey?: string,
3241
params?: { prompt?: string },
@@ -39,6 +48,7 @@ export function findActiveImageGenerationTaskForSession(
3948
});
4049
}
4150

51+
/** Lists active image generation tasks for a session. */
4252
export function listActiveImageGenerationTasksForSession(sessionKey?: string): TaskRecord[] {
4353
return listActiveMediaGenerationTasksForSession({
4454
sessionKey,
@@ -47,6 +57,7 @@ export function listActiveImageGenerationTasksForSession(sessionKey?: string): T
4757
});
4858
}
4959

60+
/** Finds an image generation task that should block duplicate generation. */
5061
export function findDuplicateGuardImageGenerationTaskForSession(
5162
sessionKey?: string,
5263
params?: { prompt?: string; requestKey?: string },
@@ -61,13 +72,15 @@ export function findDuplicateGuardImageGenerationTaskForSession(
6172
});
6273
}
6374

75+
/** Builds structured status details for one image generation task. */
6476
export function buildImageGenerationTaskStatusDetails(task: TaskRecord): Record<string, unknown> {
6577
return buildMediaGenerationTaskStatusDetails({
6678
task,
6779
sourcePrefix: IMAGE_GENERATION_SOURCE_PREFIX,
6880
});
6981
}
7082

83+
/** Builds structured status details for a list of image generation tasks. */
7184
export function buildImageGenerationTaskStatusListDetails(
7285
tasks: TaskRecord[],
7386
): Record<string, unknown> {
@@ -77,6 +90,7 @@ export function buildImageGenerationTaskStatusListDetails(
7790
});
7891
}
7992

93+
/** Builds user-facing status text for one image generation task. */
8094
export function buildImageGenerationTaskStatusText(
8195
task: TaskRecord,
8296
params?: { duplicateGuard?: boolean },
@@ -91,6 +105,7 @@ export function buildImageGenerationTaskStatusText(
91105
});
92106
}
93107

108+
/** Builds user-facing status text for active image generation tasks. */
94109
export function buildImageGenerationTaskStatusListText(tasks: TaskRecord[]): string {
95110
return buildMediaGenerationTaskStatusListText({
96111
tasks,
@@ -101,6 +116,7 @@ export function buildImageGenerationTaskStatusListText(tasks: TaskRecord[]): str
101116
});
102117
}
103118

119+
/** Builds prompt context describing an active image generation task in the session. */
104120
export function buildActiveImageGenerationTaskPromptContextForSession(
105121
sessionKey?: string,
106122
): string | undefined {

‎src/agents/openai-compatible-conversation-turn.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
/**
2+
* OpenAI-compatible conversation turn detector.
3+
*
4+
* Some providers reject requests without a non-empty user/assistant turn; this
5+
* helper checks the loose message payload shape before transport submission.
6+
*/
17
function hasNonEmptyString(value: unknown): boolean {
28
return typeof value === "string" && value.trim().length > 0;
39
}
@@ -33,6 +39,7 @@ function hasAssistantToolCall(message: Record<string, unknown>): boolean {
3339
);
3440
}
3541

42+
/** Returns whether an OpenAI-compatible messages payload contains a usable turn. */
3643
export function hasOpenAICompatibleConversationTurn(messages: unknown): boolean {
3744
if (!Array.isArray(messages)) {
3845
return false;

‎src/agents/schema/typebox.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,24 @@
1+
/**
2+
* Shared TypeBox schema helpers for agent tools.
3+
*
4+
* Tool definitions use these helpers for channel targets and common optional
5+
* numeric fields so provider-facing schemas stay consistent.
6+
*/
17
import { Type } from "typebox";
28
import {
39
CHANNEL_TARGET_DESCRIPTION,
410
CHANNEL_TARGETS_DESCRIPTION,
511
} from "../../infra/outbound/channel-target.js";
612
export { optionalStringEnum, stringEnum } from "./string-enum.js";
713

14+
/** Builds a schema for one outbound channel target. */
815
export function channelTargetSchema(options?: { description?: string }) {
916
return Type.String({
1017
description: options?.description ?? CHANNEL_TARGET_DESCRIPTION,
1118
});
1219
}
1320

21+
/** Builds a schema for multiple outbound channel targets. */
1422
export function channelTargetsSchema(options?: { description?: string }) {
1523
return Type.Array(
1624
channelTargetSchema({ description: options?.description ?? CHANNEL_TARGETS_DESCRIPTION }),
@@ -31,10 +39,12 @@ type NumberSchemaOptions = {
3139
exclusiveMaximum?: number;
3240
};
3341

42+
/** Builds an optional finite number schema with caller-provided metadata. */
3443
export function optionalFiniteNumberSchema(options: NumberSchemaOptions = {}) {
3544
return Type.Optional(Type.Number(options));
3645
}
3746

47+
/** Builds an optional positive integer schema. */
3848
export function optionalPositiveIntegerSchema(options: IntegerSchemaOptions = {}) {
3949
return Type.Optional(
4050
Type.Integer({
@@ -44,6 +54,7 @@ export function optionalPositiveIntegerSchema(options: IntegerSchemaOptions = {}
4454
);
4555
}
4656

57+
/** Builds an optional non-negative integer schema. */
4758
export function optionalNonNegativeIntegerSchema(options: IntegerSchemaOptions = {}) {
4859
return Type.Optional(
4960
Type.Integer({

‎src/agents/workspace-dirs.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
1+
/**
2+
* Agent workspace directory collection.
3+
*
4+
* File sync and cleanup paths use this to enumerate configured agent workspaces
5+
* plus the default agent workspace without duplicating agent-scope logic.
6+
*/
17
import type { OpenClawConfig } from "../config/types.openclaw.js";
28
import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "./agent-scope.js";
39

10+
/** Lists unique workspace directories for configured agents and the default agent. */
411
export function listAgentWorkspaceDirs(cfg: OpenClawConfig): string[] {
512
const dirs = new Set<string>();
613
const list = cfg.agents?.list;

0 commit comments

Comments
 (0)