@agent-native/core 0.141.7 → 0.144.1

package/corpus/templates/tasks/.agents/skills/turn-into-skill/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: turn-into-skill
+description: >-
+  Capture a proven thread or workflow as a reusable Agent-Native skill and save
+  it as a personal or organization resource. Use when a user invokes
+  `/turn-into-skill` or asks to save a workflow for reuse.
+user-invocable: true
+scope: both
+metadata:
+  internal: true
+---
+
+# Turn Into Skill
+
+This is a packaging-and-save workflow, not a request for a proposal. A skill
+is the lightweight path for a repeatable job that mostly needs guidance and
+existing app actions. Use `turn-into-app` when the job needs a dedicated UI,
+new persistent domain state, or a distinct app route.
+
+## Default behavior
+
+- With no argument, use the current thread as the source.
+- With a named skill, local workflow, transcript path, or attachment, read that
+  source and package it immediately.
+- Do not ask the user to restate context already present in the source.
+- Default to a personal skill unless the user explicitly asks for a team,
+  organization, or all-app skill, or passes `shared` as the scope.
+- If the current thread only discusses creating a skill, do not package that
+  meta-workflow unless the user explicitly asks for it.
+- Treat an explicit `/turn-into-skill` invocation as authorization to save the
+  resulting skill, but never overwrite an existing skill at the target path
+  unless the user clearly asks to update it.
+
+## 1. Extract the repeatable workflow
+
+Read the full source before writing. Reduce it to a concise working brief:
+
+- the repeatable job and the user outcome;
+- when the skill should trigger;
+- required inputs, context, permissions, and integrations;
+- the ordered steps and the one to three judgment-heavy decisions;
+- expected outputs, verification, retry, and failure boundaries.
+
+Preserve the useful judgment from the source, not its transcript. Do not turn
+one-off answers, private data, customer data, secrets, or unverified claims into
+the skill's contract. If no repeatable job can be identified, stop and report
+what is missing instead of inventing generic guidance.
+
+## 2. Author the skill
+
+Create a single `SKILL.md` with:
+
+- a short hyphen-case name and a description under 40 words that says what the
+  skill does and when to use it;
+- `user-invocable: true` so it can be selected from the app's `/` picker;
+- `scope: both` so the saved skill can guide the app runtime and connected
+  coding agents;
+- concise sections for purpose, trigger, inputs, workflow, verification, and
+  failure or retry behavior.
+
+Write imperative, reusable instructions. Keep exact action names, field rules,
+and decision criteria when they matter. Use placeholders for credentials and
+provider data. Do not paste the source transcript, large dumps, or ephemeral
+thread details into the saved skill.
+
+Choose a new slug when the target path already exists. Read an existing skill
+before changing it, and update it only when the user explicitly requested an
+update.
+
+## 3. Save at the requested scope
+
+Skills are resources at `skills/<slug>/SKILL.md`.
+
+| User intent | Save path |
+| --- | --- |
+| Just me or personal reuse | Use the `resources` tool with `action: "write"`, `scope: "personal"`, `visibility: "workspace"`, and the generated skill content. |
+| Shared organization or app reuse | Use the `resources` tool with `action: "write"`, `scope: "shared"`, `visibility: "workspace"`, and the generated skill content. |
+| Every workspace app | Use `create-workspace-resource` with `kind: "skill"`, `scope: "all"`, the generated path, name, description, and content. |
+| Only selected apps | Use the workspace resource flow with `scope: "selected"` only when the user names the app set. |
+
+For an all-app workspace skill, use the workspace resource action when it is
+available. If the current app does not expose it, discover or delegate to the
+configured Dispatch workspace agent. Do not silently save a personal skill and
+report it as shared. If organization approval is queued, report that the skill
+is pending approval rather than claiming it is active.
+
+Set `visibility: "workspace"` for an explicitly requested saved skill. Use
+`agent_scratch` only for temporary drafting, then promote or rewrite it before
+reporting the skill as saved.
+
+## 4. Verify and hand off
+
+After saving, read the exact `skills/<slug>/SKILL.md` resource back at the
+target scope. Confirm that the frontmatter name, trigger description, and full
+workflow body are present. If the read-back fails or the save returned an
+approval request, say so plainly and include the actual pending state.
+
+Report:
+
+- the skill name and path;
+- whether it is personal, organization-wide, or selected-app;
+- the trigger users can invoke from `/`;
+- the verification result and any approval or setup still required.
+
+## Related skills
+
+- `turn-into-app` — package the same source as a UI-bearing app with buttons,
+  agent handoffs, and a domain workflow.
+- `create-skill` — general skill format and authoring rules.
+- `capture-learnings` — lightweight memory for preferences and corrections,
+  rather than reusable workflows.
+- `self-modifying-code` — safety boundaries when the agent edits app source.

package/corpus/templates/tasks/.agents/skills/turn-into-skill/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Turn Into Skill"
+  short_description: "Save a proven workflow as a reusable skill"
+  default_prompt: "Read the current thread, distill the repeatable workflow into a concise user-invocable skill, save it at personal or organization scope, verify the saved resource, and report its path."

package/dist/agent/production-agent.d.ts

@@ -520,6 +520,23 @@ export declare function isCachedToolResultVisibleInContext(contextMessages: Engi
     name: string;
     input: unknown;
 }, cachedResult: string): boolean;
+/**
+ * Same tool, same error, ANY arguments. `MAX_IDENTICAL_TOOL_ERRORS` keys on the
+ * arguments too, so it only catches a model that repeats itself verbatim — and
+ * a model that is genuinely lost does the opposite: it keeps changing the
+ * arguments. Every variation mints a fresh key, the count never reaches three,
+ * and nothing stops it. That is how a delegated turn burned five minutes
+ * against an app that answers the same question in twenty-seven seconds.
+ *
+ * Higher than the exact-repeat limit on purpose: a capable model reads a schema
+ * error and fixes its arguments within a try or two, so this must not cut off
+ * honest correction. It only fires once a tool has rejected six attempts the
+ * same way, which no amount of further guessing is going to fix.
+ *
+ * This is the floor that has to hold on ANY model. A stronger model recovering
+ * on its own is not a substitute for it — it just hides its absence.
+ */
+export declare const MAX_SAME_ERROR_ACROSS_ARGUMENTS = 6;
 /**
  * Identical (tool, arguments) invocations tolerated in one turn before the turn
  * is stopped, whether or not they errored.

package/dist/agent/production-agent.js

@@ -1883,6 +1883,23 @@ export function isCachedToolResultVisibleInContext(contextMessages, toolCall, ca
 const INTERRUPTED_TOOL_RESULT_MARKER = "Interrupted before this tool returned a result.";
 const MAX_WRITE_TOOL_INTERRUPTIONS = 2;
 const MAX_IDENTICAL_TOOL_ERRORS = 3;
+/**
+ * Same tool, same error, ANY arguments. `MAX_IDENTICAL_TOOL_ERRORS` keys on the
+ * arguments too, so it only catches a model that repeats itself verbatim — and
+ * a model that is genuinely lost does the opposite: it keeps changing the
+ * arguments. Every variation mints a fresh key, the count never reaches three,
+ * and nothing stops it. That is how a delegated turn burned five minutes
+ * against an app that answers the same question in twenty-seven seconds.
+ *
+ * Higher than the exact-repeat limit on purpose: a capable model reads a schema
+ * error and fixes its arguments within a try or two, so this must not cut off
+ * honest correction. It only fires once a tool has rejected six attempts the
+ * same way, which no amount of further guessing is going to fix.
+ *
+ * This is the floor that has to hold on ANY model. A stronger model recovering
+ * on its own is not a substitute for it — it just hides its absence.
+ */
+export const MAX_SAME_ERROR_ACROSS_ARGUMENTS = 6;
 /**
  * Identical (tool, arguments) invocations tolerated in one turn before the turn
  * is stopped, whether or not they errored.
@@ -2279,8 +2296,29 @@ async function waitForInterruptedToolLedgerEntry(opts) {
     }
     return null;
 }
+/**
+ * Collapse an error to the part that identifies the FAULT, dropping the part
+ * that merely echoes this attempt's arguments.
+ *
+ * `toolInputSchemaErrorResult` embeds `Received: {…the arguments…}` in every
+ * schema rejection, so a model that keeps changing its arguments produces a new
+ * error string every time. Any breaker keyed on the raw text then sees each
+ * attempt as a first attempt and never counts — which is precisely the
+ * keeps-guessing spiral the argument-independent breaker exists to stop. An
+ * executed counterexample ran 61 turns without it firing.
+ *
+ * Dropping the echoed input costs nothing: the fault is already named by the
+ * sentence before it, and two failures that differ ONLY in the arguments they
+ * echo are the same failure.
+ */
 function normalizeToolErrorForBreaker(error) {
-    return error.replace(/\s+/g, " ").trim();
+    return (error
+        // The argument echo, up to the next sentence boundary.
+        .replace(/Received:\s*[\s\S]*?\.\s(?=Expected:|The tool was not executed)/g, "")
+        // Bare JSON payloads some providers inline instead of a Received: span.
+        .replace(/\{[\s\S]{0,2000}?\}/g, "{}")
+        .replace(/\s+/g, " ")
+        .trim());
 }
 function rateLimitRecoveryHint(message) {
     if (!/\b(?:429|rate[-\s]?limit|rate limited|quota exceeded|too many requests|calls limit exceeded)\b/i.test(message)) {
@@ -2935,6 +2973,21 @@ export async function runAgentLoop(opts) {
     const duplicateReadOnlyToolCalls = seedDuplicateReadOnlyToolCallsFromHistory(messages, actions);
     const writeToolInterruptions = seedWriteToolInterruptionsFromHistory(messages, actions);
     const repeatedToolErrors = new Map();
+    // Keyed WITHOUT the arguments — see MAX_SAME_ERROR_ACROSS_ARGUMENTS.
+    //
+    // SEEDED from earlier chunks of this turn, like `toolCallHistory` and
+    // `toolResultHistory` above. A fresh Map here would make the limit per-CHUNK
+    // rather than per-turn, and a turn may chain up to MAX_RUN_LOOP_CONTINUATIONS
+    // (6) or MAX_BACKGROUND_RUN_LOOP_CONTINUATIONS (20) of them — so the real
+    // ceiling would be 36 or 120 identical failures, not 6, and a spiral would
+    // resume with a clean slate at every chunk boundary.
+    const repeatedToolErrorsAnyArgs = new Map();
+    for (const prior of toolResultHistory) {
+        if (!prior.isError)
+            continue;
+        const key = `${prior.name}:${normalizeToolErrorForBreaker(prior.content)}`;
+        repeatedToolErrorsAnyArgs.set(key, (repeatedToolErrorsAnyArgs.get(key) ?? 0) + 1);
+    }
     const repeatedToolCalls = new Map();
     let finalGuardRetries = 0;
     let emptyFinalResponseRetries = 0;
@@ -3721,6 +3774,24 @@ export async function runAgentLoop(opts) {
                 const errorKey = `${toolCallCacheKey(toolCall.name, toolCall.input)}:${normalizeToolErrorForBreaker(sanitizedResult)}`;
                 const count = (repeatedToolErrors.get(errorKey) ?? 0) + 1;
                 repeatedToolErrors.set(errorKey, count);
+                // Same tool, same error, arguments ignored. Catches the lost-model
+                // shape the exact-match counter above cannot: new arguments every
+                // attempt, so every attempt looks like a first attempt.
+                const anyArgsKey = `${toolCall.name}:${normalizeToolErrorForBreaker(sanitizedResult)}`;
+                const anyArgsCount = (repeatedToolErrorsAnyArgs.get(anyArgsKey) ?? 0) + 1;
+                repeatedToolErrorsAnyArgs.set(anyArgsKey, anyArgsCount);
+                if (count < MAX_IDENTICAL_TOOL_ERRORS &&
+                    anyArgsCount >= MAX_SAME_ERROR_ACROSS_ARGUMENTS) {
+                    const result = `Stopped after ${anyArgsCount} attempts at ${toolCall.name} that all failed the same way ` +
+                        `with different arguments. Last error: ${sanitizedResult}`;
+                    requestedActionStop ??= {
+                        message: `I stopped because the ${toolCall.name} action rejected ${anyArgsCount} different attempts the same way, ` +
+                            "so changing the arguments again would not have worked. Anything completed before this is saved. " +
+                            `Error: ${sanitizedResult}`,
+                        errorCode: "repeated_tool_error_across_arguments",
+                    };
+                    return result;
+                }
                 if (count < MAX_IDENTICAL_TOOL_ERRORS)
                     return sanitizedResult;
                 const result = `Stopped after ${count} identical errors from ${toolCall.name} with the same arguments. ` +

package/dist/cli/agent-plugin.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Import and validate the portable Agent Plugin format.
+ *
+ * The importer intentionally handles only local plugin directories. Skills are
+ * copied as inert files, and remote Streamable HTTP MCP entries are translated
+ * to the Agent-Native `mcp.config.json` shape without copying package headers.
+ * A plugin package is not a credential store and this command never executes
+ * a plugin's scripts or stdio servers.
+ */
+export declare const AGENT_PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+export declare const AGENT_PLUGIN_MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+export interface AgentPluginManifest {
+    name: string;
+    version?: string;
+    description?: string;
+    author?: string | {
+        name: string;
+        url?: string;
+    };
+    homepage?: string;
+    repository?: string;
+    license?: string;
+    keywords?: string[];
+}
+export interface AgentPluginSkillFile {
+    relativePath: string;
+    content: Buffer;
+    mode: number;
+}
+export interface LoadedAgentPluginSkill {
+    name: string;
+    description: string;
+    relativePath: string;
+    directory: string;
+    files: AgentPluginSkillFile[];
+}
+export type AgentPluginMcpTransport = "streamable-http" | "sse" | "stdio";
+export interface LoadedAgentPluginMcpServer {
+    name: string;
+    type: AgentPluginMcpTransport;
+    url?: string;
+    command?: string;
+    args?: string[];
+    cwd?: string;
+    headerCount: number;
+}
+export interface AgentPluginSkippedComponent {
+    component: "skill" | "mcp";
+    name?: string;
+    reason: string;
+}
+export interface LoadedAgentPlugin {
+    rootDir: string;
+    manifestFile: string;
+    mcpFile?: string;
+    manifest: AgentPluginManifest;
+    pluginHash: string;
+    skills: LoadedAgentPluginSkill[];
+    mcpServers: LoadedAgentPluginMcpServer[];
+    skipped: AgentPluginSkippedComponent[];
+    warnings: string[];
+}
+export interface AgentPluginImportOptions {
+    targetDir?: string;
+    force?: boolean;
+    dryRun?: boolean;
+}
+export type AgentPluginImportItemStatus = "imported" | "unchanged" | "overwritten" | "would-import" | "would-overwrite";
+export interface AgentPluginImportSkillResult {
+    name: string;
+    sourcePath: string;
+    destination: string;
+    files: number;
+    status: AgentPluginImportItemStatus;
+}
+export interface AgentPluginImportMcpResult {
+    name: string;
+    id: string;
+    url: string;
+    headersIgnored: number;
+    status: AgentPluginImportItemStatus;
+}
+export interface AgentPluginImportResult {
+    plugin: {
+        name: string;
+        version?: string;
+        hash: string;
+        sourceDir: string;
+    };
+    targetDir: string;
+    metadataPath: string;
+    mcpConfigPath: string;
+    skills: AgentPluginImportSkillResult[];
+    mcpServers: AgentPluginImportMcpResult[];
+    skipped: AgentPluginSkippedComponent[];
+    warnings: string[];
+    dryRun: boolean;
+}
+export interface ParsedAgentPluginArgs {
+    command: "import" | "help";
+    source?: string;
+    into?: string;
+    force: boolean;
+    dryRun: boolean;
+    printJson: boolean;
+    yes: boolean;
+}
+export declare function loadAgentPlugin(input: string): LoadedAgentPlugin;
+export declare function importedMcpServerId(pluginName: string, serverName: string, existingIds?: Iterable<string>): string;
+export declare function importAgentPlugin(input: string, options?: AgentPluginImportOptions): AgentPluginImportResult;
+export declare function parseAgentPluginArgs(argv: string[]): ParsedAgentPluginArgs;
+export declare function runAgentPlugin(argv: string[]): Promise<void>;