birdclaw 0.8.1 → 0.8.3

package/src/lib/analysis-runtime.ts

@@ -0,0 +1,238 @@
+import { Effect } from "effect";
+import { tryPromise } from "./effect-runtime";
+import {
+	readOpenAIResponseStreamEffect,
+	requestOpenAIResponseEffect,
+} from "./openai-response-runtime";
+import {
+	defaultRuntimeServices,
+	type RuntimeServices,
+} from "./runtime-services";
+
+const DEFAULT_MODEL = "gpt-5.5";
+const DEFAULT_REASONING_EFFORT = "medium";
+const DEFAULT_SERVICE_TIER = "priority";
+const DEFAULT_DELIMITER_PATTERN = /\n---\s*\n/;
+
+export type AnalysisReasoningEffort = "minimal" | "low" | "medium" | "high";
+export type AnalysisServiceTier = "default" | "flex" | "priority";
+
+export interface AnalysisModelOptions {
+	model?: string;
+	reasoningEffort?: AnalysisReasoningEffort;
+	serviceTier?: AnalysisServiceTier;
+}
+
+export interface AnalysisModelSettings {
+	model: string;
+	reasoningEffort: AnalysisReasoningEffort;
+	serviceTier: AnalysisServiceTier;
+}
+
+export interface HybridAnalysisResult<T> {
+	value: T;
+	markdown: string;
+	rawText: string;
+	responseId?: string;
+	usage?: unknown;
+}
+
+function toError(error: unknown) {
+	return error instanceof Error ? error : new Error(String(error));
+}
+
+export function resolveAnalysisModelSettings(
+	options: AnalysisModelOptions,
+	runtime: RuntimeServices = defaultRuntimeServices,
+): AnalysisModelSettings {
+	return {
+		model: options.model ?? runtime.env("BIRDCLAW_AI_MODEL") ?? DEFAULT_MODEL,
+		reasoningEffort:
+			options.reasoningEffort ??
+			(runtime.env(
+				"BIRDCLAW_OPENAI_REASONING_EFFORT",
+			) as AnalysisReasoningEffort) ??
+			DEFAULT_REASONING_EFFORT,
+		serviceTier:
+			options.serviceTier ??
+			(runtime.env("BIRDCLAW_OPENAI_SERVICE_TIER") as AnalysisServiceTier) ??
+			DEFAULT_SERVICE_TIER,
+	};
+}
+
+export function createAnalysisRequestBody({
+	settings,
+	system,
+	prompt,
+	stream,
+	maxOutputTokens = 7000,
+}: {
+	settings: AnalysisModelSettings;
+	system: string;
+	prompt: string;
+	stream: boolean;
+	maxOutputTokens?: number;
+}) {
+	return {
+		model: settings.model,
+		reasoning: { effort: settings.reasoningEffort },
+		service_tier: settings.serviceTier,
+		store: false,
+		...(stream ? { stream: true } : {}),
+		max_output_tokens: maxOutputTokens,
+		input: [
+			{ role: "system", content: system },
+			{ role: "user", content: prompt },
+		],
+	};
+}
+
+export function parseHybridAnalysis<T>({
+	rawText,
+	parse,
+	fallback,
+	delimiterPattern = DEFAULT_DELIMITER_PATTERN,
+}: {
+	rawText: string;
+	parse: (value: unknown) => T;
+	fallback: (markdown: string) => T;
+	delimiterPattern?: RegExp;
+}) {
+	const [markdownPart, jsonPart] = rawText.split(delimiterPattern);
+	const markdown = (markdownPart ?? rawText).trim();
+	const candidate = jsonPart?.slice(
+		jsonPart.indexOf("{"),
+		jsonPart.lastIndexOf("}") + 1,
+	);
+	if (candidate?.startsWith("{")) {
+		try {
+			return { markdown, value: parse(JSON.parse(candidate)) };
+		} catch {
+			return { markdown, value: fallback(markdown) };
+		}
+	}
+	return { markdown, value: fallback(markdown) };
+}
+
+export function extractOpenAIResponseText(payload: Record<string, unknown>) {
+	if (typeof payload.output_text === "string") {
+		return payload.output_text;
+	}
+	const output = Array.isArray(payload.output) ? payload.output : [];
+	const parts: string[] = [];
+	for (const item of output) {
+		if (!item || typeof item !== "object") continue;
+		const content = (item as { content?: unknown }).content;
+		if (!Array.isArray(content)) continue;
+		for (const block of content) {
+			if (!block || typeof block !== "object") continue;
+			const record = block as Record<string, unknown>;
+			if (typeof record.text === "string") parts.push(record.text);
+		}
+	}
+	return parts.join("");
+}
+
+export function readHybridAnalysisStreamEffect<T>(
+	response: Response,
+	{
+		parse,
+		fallback,
+		onDelta,
+		delimiterPattern = DEFAULT_DELIMITER_PATTERN,
+	}: {
+		parse: (value: unknown) => T;
+		fallback: (markdown: string) => T;
+		onDelta?: (delta: string) => void;
+		delimiterPattern?: RegExp;
+	},
+): Effect.Effect<HybridAnalysisResult<T>, Error> {
+	return Effect.gen(function* () {
+		const stream = yield* readOpenAIResponseStreamEffect(response, {
+			delimiterPattern,
+			onDelta,
+		});
+		const parsed = parseHybridAnalysis({
+			rawText: stream.rawText,
+			parse,
+			fallback,
+			delimiterPattern,
+		});
+		return {
+			...parsed,
+			rawText: stream.rawText,
+			...(stream.responseId ? { responseId: stream.responseId } : {}),
+			...(stream.usage === undefined ? {} : { usage: stream.usage }),
+		};
+	});
+}
+
+export function streamHybridAnalysisEffect<T>({
+	body,
+	signal,
+	runtime = defaultRuntimeServices,
+	parse,
+	fallback,
+	onDelta,
+	delimiterPattern = DEFAULT_DELIMITER_PATTERN,
+}: {
+	body: unknown;
+	signal?: AbortSignal;
+	runtime?: RuntimeServices;
+	parse: (value: unknown) => T;
+	fallback: (markdown: string) => T;
+	onDelta?: (delta: string) => void;
+	delimiterPattern?: RegExp;
+}): Effect.Effect<HybridAnalysisResult<T>, Error> {
+	return Effect.gen(function* () {
+		const response = yield* requestOpenAIResponseEffect({
+			body,
+			signal,
+			runtime,
+		});
+		return yield* readHybridAnalysisStreamEffect(response, {
+			parse,
+			fallback,
+			onDelta,
+			delimiterPattern,
+		});
+	});
+}
+
+export function requestHybridAnalysisEffect<T>({
+	body,
+	signal,
+	runtime = defaultRuntimeServices,
+	parse,
+	fallback,
+	delimiterPattern = DEFAULT_DELIMITER_PATTERN,
+}: {
+	body: unknown;
+	signal?: AbortSignal;
+	runtime?: RuntimeServices;
+	parse: (value: unknown) => T;
+	fallback: (markdown: string) => T;
+	delimiterPattern?: RegExp;
+}): Effect.Effect<HybridAnalysisResult<T>, Error> {
+	return Effect.gen(function* () {
+		const response = yield* requestOpenAIResponseEffect({
+			body,
+			signal,
+			runtime,
+		});
+		const payload = (yield* tryPromise(() => response.json()).pipe(
+			Effect.mapError(toError),
+		)) as Record<string, unknown>;
+		const rawText = extractOpenAIResponseText(payload);
+		if (!rawText) {
+			return yield* Effect.fail(new Error("OpenAI returned no output text"));
+		}
+		const parsed = parseHybridAnalysis({
+			rawText,
+			parse,
+			fallback,
+			delimiterPattern,
+		});
+		return { ...parsed, rawText };
+	});
+}

package/src/lib/api-client.ts

@@ -1,109 +1,21 @@
 import { Data, Effect } from "effect";
 import { z } from "zod";
+import {
+	actionResponseSchema,
+	queryEnvelopeSchema,
+	queryResponseSchema,
+	webSyncJobSchema,
+} from "./api-contracts";
 import { runEffectPromise } from "./effect-runtime";
-import type {
-	DmConversationItem,
-	DmMessageItem,
-	QueryEnvelope,
-	QueryResponse,
-	TimelineItem,
-} from "./types";
+import {
+	defaultRuntimeServices,
+	type RuntimeServices,
+} from "./runtime-services";
 import type {
 	WebSyncJobSnapshot,
 	WebSyncKind,
 	WebSyncOptions,
-	WebSyncResponse,
 } from "./web-sync";
-
-const jsonRecordSchema = z.object({}).passthrough();
-const resourceKindSchema = z.enum(["home", "mentions", "authored", "dms"]);
-const webSyncKindSchema = z.enum([
-	"timeline",
-	"mentions",
-	"likes",
-	"bookmarks",
-	"dms",
-]);
-
-const queryEnvelopeSchema = z
-	.object({
-		accounts: z.array(jsonRecordSchema),
-		archives: z.array(jsonRecordSchema),
-		transport: z
-			.object({
-				statusText: z.string(),
-			})
-			.passthrough(),
-		stats: z.object({
-			home: z.number(),
-			mentions: z.number(),
-			dms: z.number(),
-			needsReply: z.number(),
-			inbox: z.number(),
-		}),
-	})
-	.transform((value) => value as unknown as QueryEnvelope);
-
-const queryResponseSchema = z
-	.object({
-		resource: resourceKindSchema,
-		items: z.array(jsonRecordSchema),
-		selectedConversation: z
-			.object({
-				conversation: jsonRecordSchema,
-				messages: z.array(jsonRecordSchema),
-			})
-			.nullish(),
-	})
-	.transform(
-		(value) =>
-			({
-				...value,
-				items: value.items as unknown as Array<
-					TimelineItem | DmConversationItem
-				>,
-				selectedConversation: value.selectedConversation
-					? {
-							conversation: value.selectedConversation
-								.conversation as unknown as DmConversationItem,
-							messages: value.selectedConversation
-								.messages as unknown as DmMessageItem[],
-						}
-					: value.selectedConversation,
-			}) as QueryResponse,
-	);
-
-const webSyncResponseSchema = z
-	.object({
-		ok: z.boolean(),
-		kind: webSyncKindSchema,
-		accountId: z.string().optional(),
-		summary: z.string(),
-		steps: z.array(jsonRecordSchema),
-		startedAt: z.string().optional(),
-		finishedAt: z.string().optional(),
-		inProgress: z.boolean().optional(),
-		backup: z.unknown().optional(),
-		error: z.string().optional(),
-	})
-	.transform((value) => value as unknown as WebSyncResponse);
-
-const webSyncJobSchema = z
-	.object({
-		id: z.string(),
-		kind: webSyncKindSchema,
-		accountId: z.string().optional(),
-		status: z.enum(["running", "succeeded", "failed"]),
-		startedAt: z.string(),
-		finishedAt: z.string().optional(),
-		summary: z.string(),
-		inProgress: z.boolean(),
-		result: webSyncResponseSchema.optional(),
-		error: z.string().optional(),
-	})
-	.transform((value) => value as unknown as WebSyncJobSnapshot);
-
-const actionResponseSchema = jsonRecordSchema;
 const SYNC_POLL_INTERVAL_MS = 500;
 
 export class ApiFetchError extends Data.TaggedError("ApiFetchError")<{
@@ -153,10 +65,11 @@ export function fetchJsonEffect<T>(
 	init: RequestInit | undefined,
 	schema: z.ZodType<T>,
 	fallbackMessage: string,
+	runtime: RuntimeServices = defaultRuntimeServices,
 ) {
 	return Effect.gen(function* () {
 		const response = yield* Effect.tryPromise({
-			try: () => fetch(input, init),
+			try: () => runtime.fetch(input, init),
 			catch: (cause) => apiFetchErrorFromCause(cause, fallbackMessage),
 		});
 		const data = yield* readJsonEffect(response);
@@ -187,8 +100,11 @@ export function fetchJson<T>(
 	init: RequestInit | undefined,
 	schema: z.ZodType<T>,
 	fallbackMessage: string,
+	runtime: RuntimeServices = defaultRuntimeServices,
 ): Promise<T> {
-	return runApiEffect(fetchJsonEffect(input, init, schema, fallbackMessage));
+	return runApiEffect(
+		fetchJsonEffect(input, init, schema, fallbackMessage, runtime),
+	);
 }
 
 export function fetchQueryEnvelope(init?: RequestInit) {

package/src/lib/api-contracts.ts

@@ -0,0 +1,328 @@
+import { z } from "zod";
+import type {
+	AccountRecord,
+	ArchiveCandidate,
+	DmConversationItem,
+	DmMessageItem,
+	DmSearchMatchItem,
+	EmbeddedTweet,
+	ProfileAffiliation,
+	ProfileRecord,
+	QueryEnvelope,
+	QueryResponse,
+	TimelineItem,
+	TransportStatus,
+	TweetEntities,
+	TweetMediaItem,
+	UrlExpansionItem,
+} from "./types";
+import type {
+	WebSyncJobSnapshot,
+	WebSyncResponse,
+	WebSyncStep,
+} from "./web-sync";
+
+const jsonRecordSchema = z.record(z.string(), z.unknown());
+const unknownProfile: ProfileRecord = {
+	id: "profile_unknown",
+	handle: "unknown",
+	displayName: "Unknown",
+	bio: "",
+	followersCount: 0,
+	avatarHue: 0,
+	createdAt: "",
+};
+
+const profileAffiliationSchema: z.ZodType<ProfileAffiliation> = z.object({
+	organizationProfileId: z.string(),
+	organizationName: z.string().optional(),
+	organizationHandle: z.string().optional(),
+	badgeUrl: z.string().nullable().optional(),
+	url: z.string().nullable().optional(),
+	label: z.string().nullable().optional(),
+	source: z.string(),
+	firstSeenAt: z.string(),
+	lastSeenAt: z.string(),
+	isActive: z.boolean(),
+});
+
+const profileRecordSchema = z.object({
+	id: z.string().default("profile_unknown"),
+	handle: z.string().default("unknown"),
+	displayName: z.string().default("Unknown"),
+	bio: z.string().default(""),
+	followersCount: z.number().default(0),
+	followingCount: z.number().optional(),
+	avatarHue: z.number().default(0),
+	avatarUrl: z.string().optional(),
+	location: z.string().optional(),
+	url: z.string().optional(),
+	verifiedType: z.string().optional(),
+	entities: jsonRecordSchema.optional(),
+	affiliations: z.array(profileAffiliationSchema).optional(),
+	primaryAffiliation: profileAffiliationSchema.optional(),
+	createdAt: z.string().default(""),
+}) satisfies z.ZodType<ProfileRecord>;
+
+const tweetEntitiesSchema: z.ZodType<TweetEntities> = z.object({
+	mentions: z
+		.array(
+			z.object({
+				username: z.string(),
+				id: z.string().optional(),
+				start: z.number(),
+				end: z.number(),
+				profile: profileRecordSchema.optional(),
+			}),
+		)
+		.optional(),
+	urls: z
+		.array(
+			z.object({
+				url: z.string(),
+				expandedUrl: z.string(),
+				displayUrl: z.string(),
+				start: z.number(),
+				end: z.number(),
+				title: z.string().optional(),
+				description: z.string().nullable().optional(),
+				imageUrl: z.string().nullable().optional(),
+				siteName: z.string().nullable().optional(),
+			}),
+		)
+		.optional(),
+	hashtags: z
+		.array(
+			z.object({
+				tag: z.string(),
+				start: z.number(),
+				end: z.number(),
+			}),
+		)
+		.optional(),
+	article: z
+		.object({
+			title: z.string(),
+			previewText: z.string().optional(),
+			url: z.string(),
+			coverImageUrl: z.string().optional(),
+		})
+		.optional(),
+});
+
+const tweetMediaSchema: z.ZodType<TweetMediaItem> = z.object({
+	url: z.string(),
+	type: z.enum(["image", "video", "gif", "unknown"]),
+	altText: z.string().optional(),
+	width: z.number().optional(),
+	height: z.number().optional(),
+	thumbnailUrl: z.string().optional(),
+	durationMs: z.number().optional(),
+	variants: z
+		.array(
+			z.object({
+				url: z.string(),
+				contentType: z.string().optional(),
+				bitRate: z.number().optional(),
+			}),
+		)
+		.optional(),
+});
+
+const embeddedTweetSchema: z.ZodType<EmbeddedTweet> = z.object({
+	id: z.string(),
+	text: z.string(),
+	createdAt: z.string().default(""),
+	replyToId: z.string().nullable().optional(),
+	isReplied: z.boolean().optional(),
+	likeCount: z.number().optional(),
+	mediaCount: z.number().optional(),
+	bookmarked: z.boolean().optional(),
+	liked: z.boolean().optional(),
+	author: profileRecordSchema.default(unknownProfile),
+	entities: tweetEntitiesSchema.default({}),
+	media: z.array(tweetMediaSchema).default([]),
+});
+
+const timelineItemSchema: z.ZodType<TimelineItem> = z.object({
+	id: z.string(),
+	accountId: z.string().default("acct_primary"),
+	accountHandle: z.string().default(""),
+	kind: z
+		.enum(["home", "mention", "authored", "search", "like", "bookmark"])
+		.default("home"),
+	text: z.string(),
+	searchSnippet: z.string().optional(),
+	createdAt: z.string().default(""),
+	replyToId: z.string().nullable().optional(),
+	isReplied: z.boolean().default(false),
+	likeCount: z.number().default(0),
+	mediaCount: z.number().default(0),
+	bookmarked: z.boolean().default(false),
+	liked: z.boolean().default(false),
+	author: profileRecordSchema.default(unknownProfile),
+	entities: tweetEntitiesSchema.default({}),
+	media: z.array(tweetMediaSchema).default([]),
+	replyToTweet: embeddedTweetSchema.nullable().optional(),
+	quotedTweet: embeddedTweetSchema.nullable().optional(),
+	retweetedTweet: embeddedTweetSchema.nullable().optional(),
+	qualityReason: z.string().nullable().optional(),
+});
+
+const dmMessageSchema: z.ZodType<DmMessageItem> = z.object({
+	id: z.string(),
+	conversationId: z.string().default(""),
+	text: z.string(),
+	createdAt: z.string().default(""),
+	direction: z.enum(["inbound", "outbound"]).default("inbound"),
+	isReplied: z.boolean().default(false),
+	mediaCount: z.number().default(0),
+	sender: profileRecordSchema.default(unknownProfile),
+});
+
+const urlExpansionSchema: z.ZodType<UrlExpansionItem> = z.object({
+	url: z.string(),
+	expandedUrl: z.string(),
+	finalUrl: z.string(),
+	status: z.enum(["hit", "miss", "error"]),
+	source: z.enum(["cache", "network"]),
+	title: z.string().optional(),
+	description: z.string().nullable().optional(),
+	error: z.string().optional(),
+	updatedAt: z.string(),
+});
+
+const dmSearchMatchSchema: z.ZodType<DmSearchMatchItem> = z.object({
+	message: dmMessageSchema,
+	before: z.array(dmMessageSchema),
+	after: z.array(dmMessageSchema),
+	urlExpansions: z.array(urlExpansionSchema).optional(),
+});
+
+const dmConversationSchema: z.ZodType<DmConversationItem> = z.object({
+	id: z.string(),
+	accountId: z.string(),
+	accountHandle: z.string().default(""),
+	title: z.string(),
+	searchSnippet: z.string().optional(),
+	inboxKind: z.enum(["accepted", "request"]).optional(),
+	isMessageRequest: z.boolean().optional(),
+	lastMessageAt: z.string().default(""),
+	lastMessagePreview: z.string().default(""),
+	unreadCount: z.number().default(0),
+	needsReply: z.boolean().default(false),
+	influenceScore: z.number().default(0),
+	influenceLabel: z.string().default(""),
+	participant: profileRecordSchema.default(unknownProfile),
+	matches: z.array(dmSearchMatchSchema).optional(),
+});
+
+const accountRecordSchema: z.ZodType<AccountRecord> = z.object({
+	id: z.string(),
+	name: z.string().default(""),
+	handle: z.string().default(""),
+	externalUserId: z.string().nullable().optional(),
+	profileId: z.string().optional(),
+	avatarHue: z.number().optional(),
+	avatarUrl: z.string().optional(),
+	transport: z.string().default("local"),
+	isDefault: z.coerce.number().default(0),
+	createdAt: z.string().default(""),
+});
+
+const archiveCandidateSchema: z.ZodType<ArchiveCandidate> = z.object({
+	path: z.string(),
+	name: z.string().default(""),
+	size: z.number().default(0),
+	sizeFormatted: z.string().default(""),
+	modifiedTime: z.string().default(""),
+	dateFormatted: z.string().default(""),
+});
+
+const transportStatusSchema: z.ZodType<TransportStatus> = z.object({
+	installed: z.boolean().default(false),
+	availableTransport: z.enum(["xurl", "local"]).default("local"),
+	statusText: z.string(),
+	rawStatus: z.string().optional(),
+});
+
+export const queryEnvelopeSchema: z.ZodType<QueryEnvelope> = z.object({
+	accounts: z.array(accountRecordSchema),
+	archives: z.array(archiveCandidateSchema),
+	transport: transportStatusSchema,
+	stats: z.object({
+		home: z.number(),
+		mentions: z.number(),
+		dms: z.number(),
+		needsReply: z.number(),
+		inbox: z.number(),
+	}),
+});
+
+const timelineQueryResponseSchema = z.object({
+	resource: z.enum(["home", "mentions", "authored", "search"]),
+	items: z.array(timelineItemSchema),
+	selectedConversation: z.undefined().optional(),
+});
+
+const dmQueryResponseSchema = z.object({
+	resource: z.literal("dms"),
+	items: z.array(dmConversationSchema),
+	selectedConversation: z
+		.object({
+			conversation: dmConversationSchema,
+			messages: z.array(dmMessageSchema),
+		})
+		.nullable()
+		.optional(),
+});
+
+export const queryResponseSchema: z.ZodType<QueryResponse> = z.union([
+	timelineQueryResponseSchema,
+	dmQueryResponseSchema,
+]);
+
+export const webSyncKindSchema = z.enum([
+	"timeline",
+	"mentions",
+	"likes",
+	"bookmarks",
+	"dms",
+]);
+
+const webSyncStepSchema: z.ZodType<WebSyncStep> = z.object({
+	kind: z.union([webSyncKindSchema, z.literal("mention-threads")]),
+	label: z.string(),
+	count: z.number(),
+	source: z.string().optional(),
+	partial: z.boolean().optional(),
+	warnings: z.array(z.string()).optional(),
+});
+
+export const webSyncResponseSchema: z.ZodType<WebSyncResponse> = z.object({
+	ok: z.boolean(),
+	kind: webSyncKindSchema,
+	accountId: z.string().optional(),
+	startedAt: z.string().default(""),
+	finishedAt: z.string().optional(),
+	summary: z.string(),
+	steps: z.array(webSyncStepSchema).default([]),
+	inProgress: z.boolean().optional(),
+	backup: z.custom<WebSyncResponse["backup"]>().optional(),
+	error: z.string().optional(),
+});
+
+export const webSyncJobSchema: z.ZodType<WebSyncJobSnapshot> = z.object({
+	id: z.string(),
+	kind: webSyncKindSchema,
+	accountId: z.string().optional(),
+	status: z.enum(["running", "succeeded", "failed"]),
+	startedAt: z.string(),
+	finishedAt: z.string().optional(),
+	summary: z.string(),
+	inProgress: z.boolean(),
+	result: webSyncResponseSchema.optional(),
+	error: z.string().optional(),
+});
+
+export const actionResponseSchema = jsonRecordSchema;