@oddington/sdk 0.1.35 → 0.1.36

package/dist/types/packages/sdk/src/public.d.ts

@@ -4,6 +4,8 @@ export type { RoutineSchema, RoutineSchemaValue, RoutineDefinition, RoutineInput
 export declare const defineRoutine: import('./routine-definition-types.js').DefineRoutine;
 export declare const schema: import('./routine-definition-types.js').RoutineSchemaBuilders;
 export declare const file: import('./routine-definition-types.js').RoutineFileSchema;
+export { RoutineAIError } from '../../../shared/routine-ai-contract.js';
+export type { RoutineAIOutputIssue } from '../../../shared/routine-ai-output-detail.js';
 export { InboxContractError, asksBlock, continueAsk, defineHandler, fileBlock, question, recordBlock, recordsBlock, resolveAsk, respond, richTextBlock, selection, } from '../../../shared/inbox-contract.js';
 export type { AskInput, AuthoredSource, CapturedRecords, DigestInput, Handler, HandlerReference, HandlerRuntime, HandlerTransition, InboxBlock, InboxFile, JsonObject, JsonValue, PresentedField, PresentedRecord, PresentedRecordSummary, PublishedAsk, PublishedDigest, PublishedView, PublicationRequest, Question, QuestionInput, QuestionResponse, RecordCreate, RecordDelete, RecordReference, RecordSource, RecordUpdate, RepositoryCapabilities, RepositoryReceipt, Resolution, ResolutionInput, ResponseDefinition, } from '../../../shared/inbox-contract.js';
 export type { CapturedRecordTableInput, RecordField, RecordTableInput, RecordValue, RecordViewInput, TableColumn, ViewRecord, } from '../../../shared/inbox-views.js';

package/dist/types/packages/sdk/src/routine-definition-types.d.ts

@@ -23,6 +23,7 @@ export type RoutineAI = {
     }): Promise<{
         text: string;
     }>;
+    /** Invalid output throws a catchable RoutineAIError with the original answer. */
     generateObject<Schema extends RoutineSchema<unknown>>(input: {
         instructions: string;
         input: RoutineAIInput;

package/dist/types/shared/app-routine-contract.d.ts

@@ -49,7 +49,16 @@ export declare class AppRoutineContractError extends Error {
 export declare function isAppRoutineName(value: unknown): value is string;
 /** One operation owns the property budget across input, result and all summaries. */
 export declare function parseAppRoutineContract(value: unknown): AppRoutineContract;
-export declare function validateRoutineSchemaValue(schema: AppValueSchema, value: unknown): void;
+export type RoutineSchemaIssue = {
+    reason: 'missing_field' | 'unexpected_field' | 'wrong_type' | 'out_of_bounds' | 'invalid_file';
+    path: string;
+    expected: AppValueSchema['type'];
+    received: 'missing' | 'null' | 'object' | 'array' | 'boolean' | 'string' | 'number' | 'other';
+    constraint?: 'maxLength' | 'maxItems' | 'minimum' | 'maximum';
+    limit?: number;
+};
+/** The optional observer explains the existing rejection; it never accepts or repairs a value. */
+export declare function validateRoutineSchemaValue(schema: AppValueSchema, value: unknown, rejected?: (issue: RoutineSchemaIssue) => void): void;
 /** Structural validation grants no execution or File-use authority. Values stay unchanged. */
 export declare function validateAppRoutineInput(contract: AppRoutineContract, value: unknown): void;
 export declare function validateAppRoutineResult(contract: AppRoutineContract, value?: unknown): void;

package/dist/types/shared/routine-ai-contract.d.ts

@@ -1,19 +1,32 @@
 import { type AppValueSchema } from './app-routine-contract.js';
 import { type File } from './files-contract.js';
-/** Control values, explicit text and accepted output share the Run value bound.
+import { type RoutineAIOutputIssue } from './routine-ai-output-detail.js';
+/** Requests use the Run value bound; final answers use the same UTF-8 byte ceiling.
  * Raw Files have no universal AI byte cap: adapters must measure their final
  * encoded request against their own transport limit before dispatch. */
 export declare const ROUTINE_AI_VALUE_BYTES: number;
+/** Worst-case JSON escaping is six bytes per UTF-8 answer byte, plus framing. */
+export declare const ROUTINE_AI_RESULT_BYTES: number;
 export declare const ROUTINE_AI_EVIDENCE_BYTES: number;
 export declare const ROUTINE_AI_OPERATION_MS = 120000;
 export declare const ROUTINE_AI_ERROR_CODES: readonly ['access_denied', 'capability_unavailable', 'invalid_input', 'unsupported_file', 'file_unavailable', 'input_too_large', 'output_too_large', 'provider_failure', 'invalid_output', 'cancelled'];
 export type RoutineAIErrorCode = typeof ROUTINE_AI_ERROR_CODES[number];
-/** Safe failures contain only an allowlisted code, never provider payloads. */
+/** The original answer is explicit recovery data, never part of the message or JSON logging. */
 export declare class RoutineAIError extends Error {
     readonly code: RoutineAIErrorCode;
-    constructor(code: RoutineAIErrorCode);
+    readonly detail?: RoutineAIOutputIssue;
+    readonly text?: string;
+    constructor(code: RoutineAIErrorCode, options?: {
+        detail?: RoutineAIOutputIssue;
+        text?: string;
+    });
 }
-/** Private transports carry only the bounded failure code. */
+/** Explicit private transport projection; ordinary error logging excludes answer text. */
+export declare function routineAIErrorFacts(error: RoutineAIError): {
+    code: "access_denied" | "cancelled" | "capability_unavailable" | "file_unavailable" | "input_too_large" | "invalid_input" | "invalid_output" | "output_too_large" | "provider_failure" | "unsupported_file";
+    detail?: RoutineAIOutputIssue | undefined;
+    text?: string | undefined;
+};
 export declare function parseRoutineAIError(value: unknown): RoutineAIError;
 export type RoutineAIInput = string | File;
 export type RoutineAIRequest = {
@@ -26,6 +39,7 @@ export type RoutineAIRequest = {
     input: RoutineAIInput;
     schema: AppValueSchema;
 };
+/** Keep the existing successful transport shapes for deployed SDK compatibility. */
 export type RoutineAIResult = {
     text: string;
 } | {
@@ -34,7 +48,7 @@ export type RoutineAIResult = {
 export type RoutineAITransport = (request: RoutineAIRequest) => Promise<RoutineAIResult>;
 /** Inert schema grammar only. SDK builders must be resolved before transport. */
 export declare function parseRoutineAIRequest(value: unknown): RoutineAIRequest;
-/** Validate results again at delivery; provider text is never implicitly repaired. */
+/** Delivery revalidates the existing result envelope and caller-supplied schema. */
 export declare function parseRoutineAIResult(request: RoutineAIRequest, value: unknown): RoutineAIResult;
-/** Native adapters discard reasoning and pass only the final text here. */
+/** Native adapters discard reasoning and preserve the original final text on rejection. */
 export declare function acceptRoutineAIOutput(request: RoutineAIRequest, text: unknown): RoutineAIResult;

package/dist/types/shared/routine-ai-output-detail.d.ts

@@ -0,0 +1,11 @@
+import type { RoutineSchemaIssue } from './app-routine-contract.js';
+export type RoutineAIOutputIssue = RoutineSchemaIssue | {
+    reason: 'invalid_json';
+} | {
+    reason: 'invalid_response';
+} | {
+    reason: 'empty_text';
+};
+/** Public explanations carry schema facts and types, never model values or unknown field names. */
+export declare function parseRoutineAIOutputIssue(value: unknown): RoutineAIOutputIssue | undefined;
+export declare function routineAIOutputMessage(issue: RoutineAIOutputIssue): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddington/sdk",
-  "version": "0.1.35",
+  "version": "0.1.36",
   "description": "OS routine and response-handler SDK",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",