tinker-agent 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable user-facing changes to Tinker are documented here. The project follo
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-07-22
+
+### Added
+
+- Recover automatically when an OpenAI-compatible provider completes a response
+  with reasoning only and no final answer or tool call: Tinker retries that exact
+  request once without adding the invalid response to session history.
+
+## [1.2.1] - 2026-07-22
+
+### Fixed
+
+- Ignore unrecognized top-level Agent Skill frontmatter fields while continuing to
+  validate Tinker's supported fields, so harmless extensions such as `version` no
+  longer prevent the CLI from starting. Unknown fields remain available in the
+  original `SKILL.md` content when the skill is activated.
+
 ## [1.2.0] - 2026-07-21
 
 ### Added
@@ -31,6 +48,8 @@ All notable user-facing changes to Tinker are documented here. The project follo
 - First formal npm release under the `tinker-agent` package name with the `tinker`
   executable.
 
-[Unreleased]: https://github.com/ishowshao/tinker/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/ishowshao/tinker/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/ishowshao/tinker/releases/tag/v1.3.0
+[1.2.1]: https://github.com/ishowshao/tinker/releases/tag/v1.2.1
 [1.2.0]: https://github.com/ishowshao/tinker/releases/tag/v1.2.0
 [1.1.0]: https://www.npmjs.com/package/tinker-agent/v/1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinker-agent",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "A personal coding agent with an interactive TUI and one-shot CLI.",
   "license": "Apache-2.0",
   "type": "module",

package/src/agent/loop.ts

@@ -2,7 +2,9 @@ import {
   materializeModelRequest,
   type MaterializedModelRequest,
   type ModelClient,
+  type ModelRequestOutput,
   type PreparedModelRequest,
+  ProviderResponseError,
 } from "../model/model-client";
 import type { ImageAssetStore } from "../image/image-asset-store";
 import {
@@ -83,6 +85,8 @@ export class FatalAgentTurnError extends Error {
   }
 }
 
+const MODEL_REQUEST_MAX_ATTEMPTS = 2 as const;
+
 export async function runAgent(input: RunAgentInput): Promise<RunAgentResult> {
   let lastIteration: IterationIdentity | undefined;
   const committedPrefixAuditor =
@@ -202,21 +206,15 @@ export async function runAgent(input: RunAgentInput): Promise<RunAgentResult> {
     await input.runtimeSession.append({
       type: "model.request.started",
       ...iteration,
-      data: {},
+      data: {
+        attemptNumber: 1,
+        maxAttempts: MODEL_REQUEST_MAX_ATTEMPTS,
+      },
     });
 
-    let modelOutput;
     try {
       throwIfTurnCancelled(input.signal);
       input.runtimeSession.prepareModelDispatch?.({ iteration, built });
-      modelOutput = await input.model.request(request, {
-        signal: input.signal,
-        identity: {
-          iteration,
-          runtimeSession: input.runtimeSession,
-        },
-      });
-      throwIfTurnCancelled(input.signal);
     } catch (error) {
       if (input.signal.aborted) {
         return cancelledResult(
@@ -228,6 +226,82 @@ export async function runAgent(input: RunAgentInput): Promise<RunAgentResult> {
       return failedResult(error, iteration);
     }
 
+    const requestOptions = {
+      signal: input.signal,
+      identity: {
+        iteration,
+        runtimeSession: input.runtimeSession,
+      },
+    };
+    let modelOutput: ModelRequestOutput | undefined;
+    let successfulAttempt: 1 | 2 | undefined;
+    for (const attemptNumber of [1, 2] as const) {
+      if (input.signal.aborted) {
+        return cancelledResult(
+          cancellation(input.signal, iteration, "model_request"),
+          iteration,
+        );
+      }
+      if (attemptNumber === 2) {
+        await input.runtimeSession.append({
+          type: "model.request.started",
+          ...iteration,
+          data: {
+            attemptNumber,
+            maxAttempts: MODEL_REQUEST_MAX_ATTEMPTS,
+          },
+        });
+      }
+
+      try {
+        throwIfTurnCancelled(input.signal);
+        modelOutput = await input.model.request(request, requestOptions);
+        throwIfTurnCancelled(input.signal);
+        successfulAttempt = attemptNumber;
+        break;
+      } catch (error) {
+        if (input.signal.aborted) {
+          return cancelledResult(
+            cancellation(input.signal, iteration, "model_request"),
+            iteration,
+          );
+        }
+
+        const reasoningOnly = isReasoningOnlyProviderError(error);
+        const retryDisposition = reasoningOnly
+          ? attemptNumber === 1
+            ? "scheduled"
+            : "exhausted"
+          : "not_retryable";
+        await input.runtimeSession.append({
+          type: "model.request.failed",
+          ...iteration,
+          data: modelRequestFailureData({
+            error,
+            request,
+            attemptNumber,
+            retryDisposition,
+          }),
+        });
+
+        if (retryDisposition === "scheduled") {
+          continue;
+        }
+        if (retryDisposition === "exhausted") {
+          return failedResult(
+            new Error(
+              `Provider returned reasoning without final text or tool calls in both attempts (provider=${request.provider}, model=${request.model}).`,
+            ),
+            iteration,
+          );
+        }
+        return failedResult(error, iteration);
+      }
+    }
+    if (modelOutput === undefined || successfulAttempt === undefined) {
+      throw new Error("Model request attempt state completed without an output.");
+    }
+
     try {
       input.ledger.appendAssistant({
         iteration,
@@ -245,7 +319,11 @@ export async function runAgent(input: RunAgentInput): Promise<RunAgentResult> {
     await input.runtimeSession.append({
       type: "model.request.finished",
       ...iteration,
-      data: { output: modelOutput },
+      data: {
+        attemptNumber: successfulAttempt,
+        maxAttempts: MODEL_REQUEST_MAX_ATTEMPTS,
+        output: modelOutput,
+      },
     });
     const measured = input.contextMeter.recordProviderUsage(request, modelOutput);
     await input.runtimeSession.append({
@@ -617,6 +695,32 @@ function failedResult(
   };
 }
 
+function isReasoningOnlyProviderError(error: unknown): error is ProviderResponseError {
+  return (
+    error instanceof ProviderResponseError && error.code === "reasoning_only_assistant"
+  );
+}
+
+function modelRequestFailureData(input: {
+  error: unknown;
+  request: PreparedModelRequest;
+  attemptNumber: 1 | 2;
+  retryDisposition: "scheduled" | "not_retryable" | "exhausted";
+}) {
+  const providerError =
+    input.error instanceof ProviderResponseError ? input.error : undefined;
+  return {
+    attemptNumber: input.attemptNumber,
+    maxAttempts: MODEL_REQUEST_MAX_ATTEMPTS,
+    code: providerError?.code ?? ("provider_request_error" as const),
+    retryDisposition: input.retryDisposition,
+    provider: input.request.provider,
+    model: input.request.model,
+    error: errorMessage(input.error),
+    ...(providerError === undefined ? {} : { diagnostics: providerError.diagnostics }),
+  };
+}
+
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }

package/src/events/observation-text-log.ts

@@ -45,6 +45,8 @@ export function renderObservationLogEvent(event: AgentEvent): string | undefined
       return renderTurnCancelled(event);
     case "turn.failed":
       return renderTurnFailed(event.data.error);
+    case "model.request.failed":
+      return undefined;
     default:
       return undefined;
   }

package/src/events/stdout-event-printer.ts

@@ -43,7 +43,13 @@ export class StdoutEventPrinter implements EventSink {
         );
         break;
       case "model.request.started":
-        this.stdout.write(`model.request.started iteration=${event.iterationNumber}\n`);
+        if (event.data.attemptNumber === 1) {
+          this.stdout.write(
+            `model.request.started iteration=${event.iterationNumber}\n`,
+          );
+        }
+        break;
+      case "model.request.failed":
         break;
       case "model.request.finished":
         this.stdout.write(

package/src/events/types.ts

@@ -13,7 +13,11 @@ import type {
   ToolCallId,
   TurnId,
 } from "../ids/runtime-id";
-import type { ModelRequestOutput } from "../model/model-client";
+import type {
+  ModelRequestOutput,
+  ProviderResponseDiagnostics,
+  ProviderResponseErrorCode,
+} from "../model/model-client";
 import type {
   ModelContextBudget,
   ModelContextProfile,
@@ -280,6 +284,22 @@ export type TurnFinishedData = {
   messageCount: number;
 };
 
+export type ModelRequestAttemptData = {
+  attemptNumber: 1 | 2;
+  maxAttempts: 2;
+};
+
+export type ModelRequestFailureCode = ProviderResponseErrorCode;
+
+export type ModelRequestFailedData = ModelRequestAttemptData & {
+  code: ModelRequestFailureCode;
+  retryDisposition: "scheduled" | "not_retryable" | "exhausted";
+  provider: string;
+  model: string;
+  error: string;
+  diagnostics?: ProviderResponseDiagnostics;
+};
+
 export type AgentEventDataMap = {
   "session.started": SessionStartedData;
   "session.resumed": SessionResumedData;
@@ -290,8 +310,11 @@ export type AgentEventDataMap = {
   "turn.failed": { error: string };
   "turn.cancelled": { cancellation: TurnCancellation };
   "agent.iteration.started": { iterationNumber: number };
-  "model.request.started": Record<string, never>;
-  "model.request.finished": { output: ModelRequestOutput };
+  "model.request.started": ModelRequestAttemptData;
+  "model.request.failed": ModelRequestFailedData;
+  "model.request.finished": ModelRequestAttemptData & {
+    output: ModelRequestOutput;
+  };
   "context.usage.updated": ContextUsageUpdatedData;
   "context.revision.started": ContextRevisionStartedData;
   "context.revision.finished": ContextRevisionFinishedData;
@@ -385,6 +408,7 @@ export type AgentEventInput =
   | IterationEventInput<
       | "agent.iteration.started"
       | "model.request.started"
+      | "model.request.failed"
       | "model.request.finished"
       | "context.usage.updated"
       | "context.shadow.planned"

package/src/model/model-client.ts

@@ -122,3 +122,32 @@ export type ModelUsage = {
   promptCacheMissTokens?: number;
   reasoningTokens?: number;
 };
+
+export type ProviderResponseErrorCode =
+  | "reasoning_only_assistant"
+  | "invalid_provider_response"
+  | "invalid_provider_stream"
+  | "provider_request_error";
+
+export type ProviderResponseDiagnostics = {
+  provider: string;
+  model: string;
+  path?: string;
+  finishReason?: string;
+  contentChars?: number;
+  reasoningChars?: number;
+  toolCallCount?: number;
+  usage?: ModelUsage;
+};
+
+export class ProviderResponseError extends Error {
+  constructor(
+    readonly code: ProviderResponseErrorCode,
+    message: string,
+    readonly diagnostics: ProviderResponseDiagnostics,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "ProviderResponseError";
+  }
+}

package/src/model/openai-chat-mapping.ts

@@ -5,7 +5,12 @@ import type {
   UserMessage,
 } from "../agent/types";
 import type { RuntimeSessionContext } from "../agent/runtime-session";
-import type { ModelRequestOutput, ModelUsage } from "./model-client";
+import {
+  ProviderResponseError,
+  type ModelRequestOutput,
+  type ModelUsage,
+  type ProviderResponseDiagnostics,
+} from "./model-client";
 import type { ToolDefinition } from "../tools/types";
 import type {
   ChatCompletionAssistantMessageParam,
@@ -178,21 +183,45 @@ export function fromOpenAIChatCompletion(
     "choices[0].message.content",
     options,
   );
+  const finishReason = optionalString(
+    choice.finish_reason,
+    "choices[0].finish_reason",
+    options,
+  );
+  const usage = parseUsage(completion.usage, options);
+  const reasoningContent = normalizeContent(
+    message.reasoning_content,
+    "choices[0].message.reasoning_content",
+    options,
+  );
+  const diagnostics = responseDiagnostics(options, {
+    path: "choices[0].message",
+    finishReason,
+    contentChars: content?.length ?? 0,
+    reasoningChars: reasoningContent?.length ?? 0,
+    toolCallCount: rawToolCalls.length,
+    usage,
+  });
   if ((content === null || content.trim() === "") && rawToolCalls.length === 0) {
+    if (
+      finishReason === "stop" &&
+      reasoningContent !== null &&
+      reasoningContent.trim() !== ""
+    ) {
+      throw new ProviderResponseError(
+        "reasoning_only_assistant",
+        `Invalid provider response (provider=${options.provider}, model=${options.model}): choices[0].message contains reasoning but neither non-empty final text nor tool calls.`,
+        diagnostics,
+      );
+    }
     throw providerResponseError(
       options,
       "choices[0].message",
       "has neither non-empty text nor tool calls",
+      diagnostics,
     );
   }
 
-  const finishReason = optionalString(
-    choice.finish_reason,
-    "choices[0].finish_reason",
-    options,
-  );
-  const usage = parseUsage(completion.usage, options);
-
   if (rawToolCalls.length > 0 && options.identity === undefined) {
     throw providerResponseError(
       options,
@@ -208,11 +237,7 @@ export function fromOpenAIChatCompletion(
     message: {
       role: "assistant",
       content,
-      reasoningContent: normalizeContent(
-        message.reasoning_content,
-        "choices[0].message.reasoning_content",
-        options,
-      ),
+      reasoningContent,
       toolCalls: toolCalls.length === 0 ? undefined : toolCalls,
     },
     finishReason,
@@ -513,8 +538,22 @@ function providerResponseError(
   options: { provider: string; model: string },
   path: string,
   detail: string,
-): Error {
-  return new Error(
+  diagnostics: ProviderResponseDiagnostics = responseDiagnostics(options, { path }),
+): ProviderResponseError {
+  return new ProviderResponseError(
+    "invalid_provider_response",
     `Invalid provider response (provider=${options.provider}, model=${options.model}): ${path} ${detail}.`,
+    { ...diagnostics, path },
   );
 }
+
+function responseDiagnostics(
+  options: { provider: string; model: string },
+  diagnostics: Omit<ProviderResponseDiagnostics, "provider" | "model">,
+): ProviderResponseDiagnostics {
+  return {
+    provider: options.provider,
+    model: options.model,
+    ...diagnostics,
+  };
+}

package/src/model/openai-chat-model-client.ts

@@ -11,7 +11,7 @@ import {
 import type { ImageAssetId, ImageAssetRef } from "../image/image-types";
 import type { ModelContextBudget } from "./model-context-profile";
 import type { InputTokenEstimator } from "./input-token-estimator";
-import { ModelRequestMediaAggregateError } from "./model-client";
+import { ModelRequestMediaAggregateError, ProviderResponseError } from "./model-client";
 import type {
   MaterializedModelRequest,
   ModelClient,
@@ -234,17 +234,12 @@ export class OpenAIChatModelClient implements ModelClient {
       throw new Error("Image request must be materialized before provider dispatch.");
     }
 
-    let response;
-    try {
-      response = this.stream
-        ? await this.requestStreaming(prepared, options.signal)
-        : await this.client.chat.completions.create(
-            prepared.payload as ChatCompletionCreateParamsNonStreaming,
-            { signal: options.signal },
-          );
-    } catch (error) {
-      throw sanitizedProviderError(error);
-    }
+    const response = this.stream
+      ? accumulateOpenAIChatCompletionChunks(
+          await this.collectStreamingChunks(prepared, options.signal),
+          { provider: this.provider, model: this.options.model },
+        )
+      : await this.requestNonStreaming(prepared, options.signal);
 
     return fromOpenAIChatCompletion(response, {
       identity: options.identity,
@@ -253,22 +248,37 @@ export class OpenAIChatModelClient implements ModelClient {
     });
   }
 
-  private async requestStreaming(
+  private async collectStreamingChunks(
     prepared: PreparedModelRequest,
     signal: AbortSignal,
-  ): Promise<Record<string, unknown>> {
-    const stream = await this.client.chat.completions.create(
-      prepared.payload as ChatCompletionCreateParamsStreaming,
-      { signal },
-    );
-    const chunks: unknown[] = [];
-    for await (const chunk of stream) {
-      chunks.push(chunk);
+  ): Promise<unknown[]> {
+    try {
+      const stream = await this.client.chat.completions.create(
+        prepared.payload as ChatCompletionCreateParamsStreaming,
+        { signal },
+      );
+      const chunks: unknown[] = [];
+      for await (const chunk of stream) {
+        chunks.push(chunk);
+      }
+      return chunks;
+    } catch (error) {
+      throw sanitizedProviderError(error, this.provider, this.options.model);
+    }
+  }
+
+  private async requestNonStreaming(
+    prepared: PreparedModelRequest,
+    signal: AbortSignal,
+  ) {
+    try {
+      return await this.client.chat.completions.create(
+        prepared.payload as ChatCompletionCreateParamsNonStreaming,
+        { signal },
+      );
+    } catch (error) {
+      throw sanitizedProviderError(error, this.provider, this.options.model);
     }
-    return accumulateOpenAIChatCompletionChunks(chunks, {
-      provider: this.provider,
-      model: this.options.model,
-    });
   }
 
   private assistantReplaySegments(message: AssistantMessage): PreparedPromptSegment[] {
@@ -508,7 +518,11 @@ function deepFreeze<T>(value: T): T {
   return Object.freeze(value);
 }
 
-function sanitizedProviderError(error: unknown): Error {
+function sanitizedProviderError(
+  error: unknown,
+  provider: string,
+  model: string,
+): ProviderResponseError {
   const message = error instanceof Error ? error.message : String(error);
   const sanitized = message
     .replace(
@@ -516,5 +530,10 @@ function sanitizedProviderError(error: unknown): Error {
       "[redacted image data]",
     )
     .replace(/Bearer\s+[A-Za-z0-9._~+/-]+/giu, "Bearer [redacted]");
-  return new Error(sanitized, { cause: error });
+  return new ProviderResponseError(
+    "provider_request_error",
+    sanitized,
+    { provider, model },
+    { cause: error },
+  );
 }

package/src/model/openai-chat-stream.ts

@@ -1,3 +1,5 @@
+import { ProviderResponseError } from "./model-client";
+
 type ProviderContext = { provider: string; model: string };
 
 type ToolCallAccumulator = {
@@ -265,8 +267,10 @@ function providerStreamError(
   options: ProviderContext,
   path: string,
   detail: string,
-): Error {
-  return new Error(
+): ProviderResponseError {
+  return new ProviderResponseError(
+    "invalid_provider_stream",
     `Invalid provider stream (provider=${options.provider}, model=${options.model}): ${path} ${detail}.`,
+    { provider: options.provider, model: options.model, path },
   );
 }

package/src/skills/skill-loader.ts

@@ -86,15 +86,6 @@ type ScopeRoot = {
   canonicalRoot: string;
 };
 
-const SKILL_FIELDS = Object.freeze([
-  "name",
-  "description",
-  "license",
-  "compatibility",
-  "metadata",
-  "allowed-tools",
-] as const);
-
 const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
 export async function loadSkillCatalog(input: {
@@ -519,17 +510,6 @@ function parseSkillDocument(
   if (!isPlainRecord(value)) {
     throw frontmatterError(scope, directoryName, "root must be a plain mapping");
   }
-  const unknown = Object.keys(value).filter(
-    (key) => !(SKILL_FIELDS as readonly string[]).includes(key),
-  );
-  if (unknown.length > 0) {
-    throw fieldError(
-      scope,
-      directoryName,
-      `contains unknown field ${JSON.stringify(unknown.sort(compareText)[0])}`,
-    );
-  }
-
   const name = requireStringField(value, "name", scope, directoryName);
   const description = requireStringField(value, "description", scope, directoryName);
   if (

package/src/tui/event-store.ts

@@ -153,13 +153,21 @@ export function reduceTuiProjection(
     }
     case "model.request.started":
       return updateActiveTurn(state, event, policy, (turn) =>
-        appendTurnItem(turn, {
-          id: `model-${event.iterationId}`,
-          ref: modelRequestRef(event.iterationId),
-          text: `model iteration ${event.iterationNumber}`,
-          status: "running",
-        }),
+        event.data.attemptNumber === 1
+          ? appendTurnItem(turn, {
+              id: `model-${event.iterationId}`,
+              ref: modelRequestRef(event.iterationId),
+              text: `model iteration ${event.iterationNumber}`,
+              status: "running",
+            })
+          : updateTurnItem(turn, modelRequestRef(event.iterationId), (item) => ({
+              ...item,
+              text: `model iteration ${event.iterationNumber} · retrying`,
+              status: "running",
+            })),
       );
+    case "model.request.failed":
+      return state;
     case "model.request.finished":
       return updateActiveTurn(state, event, policy, (turn) =>
         updateTurnItem(turn, modelRequestRef(event.iterationId), (item) => ({
@@ -333,7 +341,7 @@ export function reduceTuiProjection(
     }
     case "turn.failed": {
       const active = requireActiveTurn(state, event);
-      const failed = appendTurnItem(active, {
+      const failed = appendTurnItem(markRunningItemsFailed(active), {
         id: `turn-${active.turnId}-failed-${event.eventSequence}`,
         label: "error",
         text: event.data.error,
@@ -467,6 +475,15 @@ function appendTurnItem(
   return { ...turn, items: [...turn.items, item] };
 }
 
+function markRunningItemsFailed(turn: TuiTurnProjection): TuiTurnProjection {
+  return {
+    ...turn,
+    items: turn.items.map((item) =>
+      item.status === "running" ? { ...item, status: "failed" } : item,
+    ),
+  };
+}
+
 function updateTurnItem(
   turn: TuiTurnProjection,
   ref: string,