@zackbart/connecta 0.19.0 → 0.21.0

package/dist/meta-tools.js

@@ -94,480 +94,6 @@ export function alignEndToCharBoundary(bytes, offset, end, total) {
     }
     return e;
 }
-/** Resolve a dot-path and retain misses below every `[]` boundary. */
-function resolvePath(value, segments) {
-    const seg = segments[0];
-    if (seg === undefined) {
-        return value === undefined
-            ? { status: "unmatched" }
-            : { status: "matched", value };
-    }
-    const rest = segments.slice(1);
-    const isArr = seg.endsWith("[]");
-    const key = isArr ? seg.slice(0, -2) : seg;
-    let next = value;
-    if (key !== "") {
-        if (value === null || typeof value !== "object") {
-            return { status: "unmatched" };
-        }
-        next = value[key];
-    }
-    if (isArr) {
-        if (!Array.isArray(next))
-            return { status: "unmatched" };
-        if (next.length === 0)
-            return { status: "matched", value: [] };
-        const elements = next.map((el) => resolvePath(el, rest));
-        const matched = elements.some((element) => element.status !== "unmatched");
-        const missed = elements.some((element) => element.status !== "matched");
-        if (!matched)
-            return { status: "unmatched" };
-        return {
-            status: missed ? "partial" : "matched",
-            // Undefined placeholders retain the historical array positions in the
-            // partial value. JSON renders them as null; partialFields says they are
-            // unresolved rather than genuine downstream nulls.
-            value: elements.map((element) => element.status === "unmatched" ? undefined : element.value),
-        };
-    }
-    return resolvePath(next, rest);
-}
-const MAX_PROJECTION_AVAILABLE_FIELDS = 20;
-const MAX_PROJECTION_SCHEMA_DEPTH = 12;
-const MAX_PROJECTION_SCHEMA_NODES = 200;
-const MAX_PROJECTION_SCHEMA_PATHS = 100;
-const MAX_PROJECTION_PATH_CHARS = 256;
-const MAX_PROJECTION_PATH_BYTES = 512;
-const MAX_PROJECTION_TOTAL_PATH_CHARS = 512;
-const MAX_PROJECTION_TOTAL_PATH_BYTES = 768;
-const JSON_SCHEMA_TYPES = new Set([
-    "array",
-    "boolean",
-    "integer",
-    "null",
-    "number",
-    "object",
-    "string",
-]);
-const NON_SEMANTIC_REF_SIBLINGS = new Set([
-    "$anchor",
-    "$comment",
-    "$defs",
-    "$id",
-    "$ref",
-    "$schema",
-    "default",
-    "definitions",
-    "deprecated",
-    "description",
-    "examples",
-    "readOnly",
-    "title",
-    "writeOnly",
-]);
-function localSchemaRef(root, ref) {
-    if (ref === "#")
-        return root;
-    if (!ref.startsWith("#/") ||
-        ref.length > 2_048 ||
-        /~(?![01])/.test(ref)) {
-        return undefined;
-    }
-    const segments = ref.slice(2).split("/");
-    if (segments.length > MAX_PROJECTION_SCHEMA_DEPTH)
-        return undefined;
-    let current = root;
-    for (const encoded of segments) {
-        if (current === null || typeof current !== "object")
-            return undefined;
-        const key = encoded.replaceAll("~1", "/").replaceAll("~0", "~");
-        if (!Object.prototype.hasOwnProperty.call(current, key))
-            return undefined;
-        current = current[key];
-    }
-    return current;
-}
-function hasSchemaType(schema, wanted) {
-    return (schema.type === wanted ||
-        (Array.isArray(schema.type) && schema.type.includes(wanted)));
-}
-function selectableFieldName(name) {
-    return name.length > 0 && !name.includes(".") && !name.endsWith("[]");
-}
-/**
- * Collect selectable output paths without trusting a schema more than JSON
- * Schema permits. Traversal is iterative and budgeted before sorting or
- * rendering, so a cyclic, extremely deep, or extremely broad downstream
- * schema cannot turn projection feedback into unbounded host work.
- */
-function analyzeSchemaFields(root) {
-    const pending = [
-        { schema: root, prefix: "", depth: 0, ancestors: new Set() },
-    ];
-    const paths = new Set();
-    let nodes = 0;
-    let totalPathChars = 0;
-    let totalPathBytes = 0;
-    let complete = true;
-    let truncated = false;
-    const addPath = (path) => {
-        if (paths.has(path))
-            return true;
-        // Check UTF-16 length before encoding, so a hostile multi-megabyte key
-        // never causes a same-sized temporary allocation merely to reject it.
-        if (path.length > MAX_PROJECTION_PATH_CHARS ||
-            totalPathChars + path.length > MAX_PROJECTION_TOTAL_PATH_CHARS) {
-            complete = false;
-            truncated = true;
-            return false;
-        }
-        const pathBytes = enc.encode(path).length;
-        if (pathBytes > MAX_PROJECTION_PATH_BYTES ||
-            totalPathBytes + pathBytes > MAX_PROJECTION_TOTAL_PATH_BYTES ||
-            paths.size >= MAX_PROJECTION_SCHEMA_PATHS) {
-            complete = false;
-            truncated = true;
-            return false;
-        }
-        paths.add(path);
-        totalPathChars += path.length;
-        totalPathBytes += pathBytes;
-        return true;
-    };
-    const enqueue = (item) => {
-        if (nodes + pending.length >= MAX_PROJECTION_SCHEMA_NODES) {
-            complete = false;
-            truncated = true;
-            return false;
-        }
-        pending.push(item);
-        return true;
-    };
-    while (pending.length > 0) {
-        const item = pending.pop();
-        if (item.depth > MAX_PROJECTION_SCHEMA_DEPTH) {
-            complete = false;
-            truncated = true;
-            continue;
-        }
-        if (++nodes > MAX_PROJECTION_SCHEMA_NODES) {
-            complete = false;
-            truncated = true;
-            break;
-        }
-        if (item.schema === false)
-            continue;
-        if (item.schema === true ||
-            item.schema === null ||
-            typeof item.schema !== "object" ||
-            item.ancestors.has(item.schema)) {
-            complete = false;
-            continue;
-        }
-        const schema = item.schema;
-        const ancestors = new Set(item.ancestors).add(item.schema);
-        let recognized = false;
-        if (schema.type !== undefined &&
-            !((typeof schema.type === "string" &&
-                JSON_SCHEMA_TYPES.has(schema.type)) ||
-                (Array.isArray(schema.type) &&
-                    schema.type.length > 0 &&
-                    schema.type.every((type) => typeof type === "string" && JSON_SCHEMA_TYPES.has(type))))) {
-            complete = false;
-        }
-        if (schema.$ref !== undefined) {
-            recognized = true;
-            let hasSemanticSiblings = false;
-            for (const key in schema) {
-                if (Object.prototype.hasOwnProperty.call(schema, key) &&
-                    !NON_SEMANTIC_REF_SIBLINGS.has(key)) {
-                    hasSemanticSiblings = true;
-                    break;
-                }
-            }
-            if (hasSemanticSiblings) {
-                // Modern JSON Schema applies $ref siblings as an intersection. A
-                // compact field walker cannot prove that intersection's selectable
-                // paths, so do not publish paths from either half as available.
-                complete = false;
-                continue;
-            }
-            const target = typeof schema.$ref === "string"
-                ? localSchemaRef(root, schema.$ref)
-                : undefined;
-            if (target === undefined)
-                complete = false;
-            else {
-                enqueue({
-                    schema: target,
-                    prefix: item.prefix,
-                    depth: item.depth + 1,
-                    ancestors,
-                });
-            }
-        }
-        for (const keyword of ["allOf", "anyOf", "oneOf"]) {
-            const variants = schema[keyword];
-            if (!Array.isArray(variants))
-                continue;
-            recognized = true;
-            // Combining schemas can close or conditionally expose fields in ways
-            // this compact recovery walker intentionally does not prove.
-            complete = false;
-            for (const variant of variants) {
-                if (!enqueue({
-                    schema: variant,
-                    prefix: item.prefix,
-                    depth: item.depth + 1,
-                    ancestors,
-                })) {
-                    break;
-                }
-            }
-        }
-        if (truncated)
-            break;
-        const properties = schema.properties;
-        const propertyRecord = properties !== null &&
-            typeof properties === "object" &&
-            !Array.isArray(properties)
-            ? properties
-            : undefined;
-        if (properties !== undefined && propertyRecord === undefined) {
-            complete = false;
-        }
-        const objectShape = hasSchemaType(schema, "object") || propertyRecord !== undefined;
-        if (objectShape) {
-            recognized = true;
-            const patterns = schema.patternProperties;
-            let hasPatterns = false;
-            if (patterns !== undefined &&
-                (patterns === null ||
-                    typeof patterns !== "object" ||
-                    Array.isArray(patterns))) {
-                complete = false;
-            }
-            else if (patterns !== undefined) {
-                for (const key in patterns) {
-                    if (Object.prototype.hasOwnProperty.call(patterns, key)) {
-                        hasPatterns = true;
-                        break;
-                    }
-                }
-            }
-            if (schema.additionalProperties !== false || hasPatterns) {
-                complete = false;
-            }
-            if (propertyRecord) {
-                for (const key in propertyRecord) {
-                    if (!Object.prototype.hasOwnProperty.call(propertyRecord, key)) {
-                        continue;
-                    }
-                    if (++nodes > MAX_PROJECTION_SCHEMA_NODES) {
-                        complete = false;
-                        truncated = true;
-                        break;
-                    }
-                    if (key.length > MAX_PROJECTION_PATH_CHARS) {
-                        complete = false;
-                        truncated = true;
-                        break;
-                    }
-                    if (!selectableFieldName(key)) {
-                        complete = false;
-                        continue;
-                    }
-                    const child = propertyRecord[key];
-                    // A false property schema forbids the property; advertising its name
-                    // as selectable would turn an impossible value into a valid hint.
-                    if (child === false)
-                        continue;
-                    const path = item.prefix ? `${item.prefix}.${key}` : key;
-                    if (!addPath(path))
-                        break;
-                    if (!enqueue({
-                        schema: child,
-                        prefix: path,
-                        depth: item.depth + 1,
-                        ancestors,
-                    })) {
-                        break;
-                    }
-                }
-            }
-        }
-        if (truncated)
-            break;
-        const arrayShape = hasSchemaType(schema, "array") ||
-            schema.items !== undefined ||
-            schema.prefixItems !== undefined;
-        if (arrayShape) {
-            recognized = true;
-            const arrayPath = `${item.prefix}[]`;
-            if (addPath(arrayPath)) {
-                if (Array.isArray(schema.prefixItems)) {
-                    complete = false;
-                    for (const child of schema.prefixItems) {
-                        if (!enqueue({
-                            schema: child,
-                            prefix: arrayPath,
-                            depth: item.depth + 1,
-                            ancestors,
-                        })) {
-                            break;
-                        }
-                    }
-                }
-                if (schema.items === undefined) {
-                    if (!Array.isArray(schema.prefixItems))
-                        complete = false;
-                }
-                else if (schema.items === true || Array.isArray(schema.items)) {
-                    complete = false;
-                    const children = Array.isArray(schema.items)
-                        ? schema.items
-                        : [];
-                    for (const child of children) {
-                        if (!enqueue({
-                            schema: child,
-                            prefix: arrayPath,
-                            depth: item.depth + 1,
-                            ancestors,
-                        })) {
-                            break;
-                        }
-                    }
-                }
-                else if (schema.items !== false) {
-                    enqueue({
-                        schema: schema.items,
-                        prefix: arrayPath,
-                        depth: item.depth + 1,
-                        ancestors,
-                    });
-                }
-            }
-        }
-        const types = Array.isArray(schema.type)
-            ? schema.type
-            : schema.type === undefined
-                ? []
-                : [schema.type];
-        const primitiveOnly = types.length > 0 &&
-            types.every((type) => type === "string" ||
-                type === "number" ||
-                type === "integer" ||
-                type === "boolean" ||
-                type === "null");
-        if (!recognized && !primitiveOnly)
-            complete = false;
-        if (truncated)
-            break;
-    }
-    return {
-        paths: [...paths].sort(),
-        complete,
-        truncated,
-    };
-}
-function schemaProjectionFeedback(outputSchema, unmatchedFields) {
-    const analysis = analyzeSchemaFields(outputSchema);
-    const available = new Set(analysis.paths);
-    const invalidFields = analysis.complete
-        ? unmatchedFields.filter((field) => !available.has(field))
-        : [];
-    const missingArrayMarker = unmatchedFields.some((field) => analysis.paths.some((availableField) => availableField.includes("[]") &&
-        availableField.replaceAll("[]", "") === field));
-    return {
-        ...(missingArrayMarker
-            ? {
-                hint: 'Traverse arrays with [] after the array field name, for example "results[].id".',
-            }
-            : {}),
-        schemaDeclared: true,
-        schemaCoverage: analysis.complete ? "complete" : "partial",
-        ...(invalidFields.length > 0 ? { invalidFields } : {}),
-        ...(analysis.paths.length > 0
-            ? {
-                availableFields: analysis.paths.slice(0, MAX_PROJECTION_AVAILABLE_FIELDS),
-            }
-            : {}),
-        ...(analysis.truncated ||
-            analysis.paths.length > MAX_PROJECTION_AVAILABLE_FIELDS
-            ? { availableFieldsTruncated: true }
-            : {}),
-    };
-}
-/** Select the given dot-paths, retaining both matches and exact misses. */
-function applyFields(value, fields) {
-    const out = {};
-    const unmatchedFields = [];
-    const partialFields = [];
-    for (const path of fields) {
-        const resolved = resolvePath(value, path.split("."));
-        if (resolved.status === "unmatched") {
-            unmatchedFields.push(path);
-        }
-        else {
-            out[path] = resolved.value;
-            if (resolved.status === "partial")
-                partialFields.push(path);
-        }
-    }
-    return { data: out, unmatchedFields, partialFields };
-}
-/**
- * Keep the historical flat projection when every path resolves. A miss gets a
- * wrapper with a reserved discriminator so neither `{}` nor downstream fields
- * named `data` / `projection` can be mistaken for projection feedback.
- */
-function projectionValue(value, fields, outputSchema) {
-    const projected = applyFields(value, fields);
-    // `$connecta` is reserved at the top level of a projection. Even a fully
-    // matched downstream field with that exact name is escaped below `data`, so
-    // no user-controlled value can impersonate Connecta's discriminator.
-    const reservedCollision = Object.prototype.hasOwnProperty.call(projected.data, "$connecta");
-    if (projected.unmatchedFields.length === 0 &&
-        projected.partialFields.length === 0 &&
-        !reservedCollision) {
-        return projected.data;
-    }
-    const problemFields = [
-        ...projected.unmatchedFields,
-        ...projected.partialFields,
-    ];
-    return {
-        data: projected.data,
-        $connecta: {
-            type: "field_projection",
-            unmatchedFields: projected.unmatchedFields,
-            ...(projected.partialFields.length > 0
-                ? { partialFields: projected.partialFields }
-                : {}),
-            ...(outputSchema
-                ? schemaProjectionFeedback(outputSchema, problemFields)
-                : {}),
-        },
-    };
-}
-/** Apply fields to each JSON-parseable text block; non-JSON blocks pass through. */
-function applyFieldsToContent(content, fields, outputSchema) {
-    return content.map((b) => {
-        if (b.type !== "text")
-            return b;
-        let parsed;
-        try {
-            parsed = JSON.parse(b.text);
-        }
-        catch {
-            return b;
-        }
-        return {
-            ...b,
-            text: JSON.stringify(projectionValue(parsed, fields, outputSchema)),
-        };
-    });
-}
 // --- result-size guard + get_result (feature 1) ---------------------------
 /**
  * The one serialization every result guard measures, stashes, and pages: JSON
@@ -595,7 +121,7 @@ async function stashResult(text, results, totalBytes) {
         truncated: true,
         resultId: id,
         totalBytes,
-        hint: "use get_result {id, offset} to page, or re-call with fields to select less",
+        hint: "use get_result {id, offset} to page the complete direct-call result",
         nextAction: {
             tool: "get_result",
             arguments: { id, offset: 0 },
@@ -734,7 +260,6 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
     /** MCP adapter: shared invocation semantics plus MCP-only result shaping. */
     async function runCall(call, source, options = {}) {
         const results = registry.resultsStorage();
-        const fields = call.fields && call.fields.length > 0 ? call.fields : null;
         const timeoutMs = normalizeTimeoutMs(call.timeoutMs) ?? defaultToolTimeoutMs;
         const outcome = await invocation.invoke(call.address, call.args ?? {}, {
             source,
@@ -763,25 +288,18 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     ...(truncated ? { friction: "result_too_large" } : {}),
                 });
                 if (call.resultMode === "value") {
-                    let value = fields
-                        ? projectionValue(result, fields, resolved.definition.outputSchema)
-                        : result;
+                    let value = result;
                     const guarded = await guardValue(value, results, cap);
                     value = guarded.result;
                     return processed(jsonResult({ ok: true, data: value }), guarded.truncated, { value });
                 }
                 if (resolved.connector.kind === "mcp") {
                     const mcpResult = result;
-                    let content = mcpResult?.content ?? [];
-                    if (fields) {
-                        content = applyFieldsToContent(content, fields, resolved.definition.outputSchema);
-                    }
+                    const content = mcpResult?.content ?? [];
                     const guarded = await guardContent(content, results, cap);
                     return processed(guarded.result, guarded.truncated);
                 }
-                const value = fields
-                    ? projectionValue(result, fields, resolved.definition.outputSchema)
-                    : result;
+                const value = result;
                 const guarded = await guardText(serializeResultText(value), results, cap);
                 return processed(guarded.result, guarded.truncated, { value });
             },
@@ -867,7 +385,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         },
         async callDestructiveTool(args) {
             // `reason` is read by the host's approval view and stops there — runCall
-            // forwards only the call fields, so it never reaches the connector.
+            // forwards only the call arguments, so it never reaches the connector.
             return (await runCall(args, "call_destructive_tool", { allowDestructive: true })).toolResult;
         },
         async getResult(args) {
@@ -997,12 +515,12 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         },
     };
 }
-const SEARCH_DESC = `Use top-level search for one unknown-address read before call_tool, or for approval-required work before call_destructive_tool. Use 2–4 action/object terms and includeSchemas="compact"; the default limit is ${DEFAULT_SEARCH_LIMIT}. Set connector when known. safety="readOnly" finds direct or program calls; "approvalRequired" finds the fail-closed complement. These filters grant no authority. For multiple, dependent, or reduced read-only calls, use one execute_code program instead. Empty query browses.`;
-const CALL_DESC = 'Call one tool explicitly annotated readOnlyHint: true. Use execute_code for multiple, dependent, or reduced read-only calls. Unannotated or write-capable tools fail closed to call_destructive_tool. fields projects JSON dot-paths; use [] through arrays. A truncated result carries a get_result action.';
+const SEARCH_DESC = `Use top-level search for catalog inspection or approval-required work before call_destructive_tool. Unknown-address read-only work belongs in one execute_code program that searches, calls, and returns the answer. Use 2–4 action/object terms and includeSchemas="compact"; the default limit is ${DEFAULT_SEARCH_LIMIT}. Set connector when known. safety="readOnly" finds direct or program calls; "approvalRequired" finds the fail-closed complement. These filters grant no authority. Empty query browses.`;
+const CALL_DESC = 'Call one known-address tool explicitly annotated readOnlyHint: true. Use execute_code for unknown-address, multiple, dependent, or reduced read-only work. Unannotated or write-capable tools fail closed to call_destructive_tool. A truncated result carries a get_result action.';
 const CALL_DESTRUCTIVE_DESC = "Call any tool not explicitly annotated readOnlyHint: true. Include a short reason for the human reviewer after checking the schema and consequences. The reason grants no authority and is not sent downstream.";
 const GET_RESULT_DESC = "Page a truncated direct-call result by id and byte offset. A program result is never paged; reduce it inside execute_code. Returns text, offset, nextOffset when more remains, and totalBytes.";
 const AUTHORIZE_DESC = "Use after auth_required. Returns an OAuth or operator-credential handoff, or reports required deployment configuration. force=true restarts OAuth only; this tool never accepts credentials.";
-const SKILLS_DESC = 'List or fetch on-demand guidance. Fetch usage once per task for program syntax, selection, repair, examples, and runtime details.';
+const SKILLS_DESC = 'List or fetch on-demand guidance. Fetch usage only when the always-loaded instructions are insufficient or a program needs repair.';
 /**
  * Sentences appended to a meta-tool description only when this connection
  * actually has connector guides. Tool descriptions are always-loaded context,
@@ -1043,7 +561,6 @@ const READ_ONLY_LOCAL = {
 const CALL_INPUT_SCHEMA = {
     address: z.string(),
     args: z.record(z.string(), z.unknown()).optional(),
-    fields: z.array(z.string()).optional(),
     resultMode: z.enum(["mcp", "value"]).optional(),
     timeoutMs: z.number().int().positive().optional(),
     maxRetries: z.number().int().min(0).max(2).optional(),
@@ -1094,10 +611,8 @@ export function registerMetaTools(server, registry, ctx) {
         // call_tool admits only tools that are themselves explicitly read-only;
         // anything else is refused and routed to call_destructive_tool.
         annotations: READ_ONLY_REMOTE,
-        // The trusted program-view shell delegates bounded named reads here.
-        // It is already one of the seven model tools; app visibility adds no
-        // tool and this handler repeats ordinary fail-closed read admission.
-        _meta: { ui: { visibility: ["model", "app"] } },
+        // Omission defaults to model + app. Display-only views may call no tool.
+        _meta: { ui: { visibility: ["model"] } },
     }, async (args) => mt.callTool(args));
     server.registerTool("call_destructive_tool", {
         description: describedFor(registry, CALL_DESTRUCTIVE_DESC, "destructive"),