@namzu/sdk 49.0.0 → 50.1.0

package/dist/pals/reference-images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-images.d.ts","sourceRoot":"","sources":["../../src/pals/reference-images.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAA;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAYzE,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IACjC,4FAA4F;IAC5F,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACtB;AAED,uEAAuE;AACvE,MAAM,WAAW,8BAA8B;IAC9C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,8BAA8B;IAC9C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,6FAA6F;IAC7F,QAAQ,CAAC,sBAAsB,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3D,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC7B;AAED,MAAM,WAAW,4BAA4B;IAC5C,4FAA4F;IAC5F,QAAQ,CAAC,WAAW,EAAE,MAAM,SAAS,iBAAiB,EAAE,CAAA;IACxD,QAAQ,CAAC,sBAAsB,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/E;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACxC,WAAW,EAAE,SAAS,iBAAiB,EAAE,GACvC,SAAS,iBAAiB,EAAE,CA+C9B;AAoED;;;GAGG;AACH,wBAAsB,wBAAwB,CAC7C,UAAU,EAAE,SAAS,iBAAiB,EAAE,EACxC,OAAO,EAAE,8BAA8B,GACrC,OAAO,CAAC,SAAS,8BAA8B,EAAE,CAAC,CAwGpD;AAED,sFAAsF;AACtF,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,4BAA4B,GAAG,cAAc,CAmCjG"}

package/dist/pals/reference-images.js

@@ -0,0 +1,248 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { posix } from 'node:path';
+import { z } from 'zod';
+import { admitMcpImageBatch } from '../connector/mcp/image-admission.js';
+import { defineTool } from '../tools/defineTool.js';
+const MAX_IMAGES = 8;
+const MAX_IMAGE_BYTES = 3 * 1024 * 1024;
+const MAX_BATCH_BYTES = 12 * 1024 * 1024;
+const EXTENSIONS = {
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/webp': 'webp',
+    'image/gif': 'gif',
+};
+/**
+ * Validate a complete reference batch before allocating or writing any guest file.
+ * URLs and stored references need a host-owned resolver; this API never fetches them.
+ */
+export function preparePalReferenceImages(attachments) {
+    const references = [];
+    let total = 0;
+    for (const [index, attachment] of attachments.entries()) {
+        if (attachment.type === 'document')
+            continue;
+        if (attachment.type === 'stored') {
+            if (attachment.kind === 'image')
+                throw new Error('Stored image references require an explicit host-owned resolver before guest import.');
+            continue;
+        }
+        if (attachment.type !== undefined && attachment.type !== 'image')
+            throw new Error('Unsupported reference attachment type.');
+        if (references.length >= MAX_IMAGES)
+            throw new Error(`Reference import allows at most ${MAX_IMAGES} images per input.`);
+        if (typeof attachment.data !== 'string' ||
+            attachment.data.length > 4 * Math.ceil(MAX_IMAGE_BYTES / 3))
+            throw new Error(`Each reference image must fit within ${MAX_IMAGE_BYTES} bytes.`);
+        if (!EXTENSIONS[attachment.mediaType] ||
+            !admitMcpImageBatch([
+                {
+                    type: 'image',
+                    data: attachment.data,
+                    mimeType: attachment.mediaType,
+                },
+            ]))
+            throw new Error(`Reference attachment ${index + 1} is not a complete supported raster image.`);
+        const bytes = Buffer.from(attachment.data, 'base64');
+        total += bytes.length;
+        if (bytes.length > MAX_IMAGE_BYTES || total > MAX_BATCH_BYTES)
+            throw new Error(`Reference images must fit within ${MAX_BATCH_BYTES} bytes per input.`);
+        references.push(Object.freeze({
+            attachmentIndex: index + 1,
+            mediaType: attachment.mediaType,
+            data: attachment.data,
+            sha256: createHash('sha256').update(bytes).digest('hex'),
+            bytes: bytes.length,
+        }));
+    }
+    return Object.freeze(references);
+}
+// The shipped Pal guest has Python 3. All I/O below occurs through the admitted
+// sandbox; a missing guest interpreter fails rather than running anything locally.
+// Directory descriptors and O_NOFOLLOW protect the reference store from symlinks;
+// link() publishes a new file exclusively and never replaces an existing reference.
+const IMPORT_SCRIPT = String.raw `
+import fcntl, hashlib, json, os, stat, sys
+request = json.loads(sys.argv[1])
+flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
+root = os.open(request['root'], flags)
+def directory(parent, name):
+    try: os.mkdir(name, 0o700, dir_fd=parent)
+    except FileExistsError: pass
+    return os.open(name, flags, dir_fd=parent)
+store = directory(root, '.namzu')
+refs = directory(store, 'references')
+imports = directory(store, 'reference-imports')
+lock = os.open('.reference-lock', os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600, dir_fd=store)
+if not stat.S_ISREG(os.fstat(lock).st_mode): raise RuntimeError('Reference lock is not a regular file')
+fcntl.flock(lock, fcntl.LOCK_EX)
+def verify(parent, name, item):
+    try: fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=parent)
+    except FileNotFoundError: return False
+    with os.fdopen(fd, 'rb') as file:
+        info = os.fstat(file.fileno())
+        if not stat.S_ISREG(info.st_mode) or info.st_size != item['bytes']:
+            raise RuntimeError('Reference file collision or invalid staging file')
+        if hashlib.sha256(file.read(item['bytes'] + 1)).hexdigest() != item['sha256']:
+            raise RuntimeError('Reference file collision or invalid staging bytes')
+    return True
+phase = request['phase']
+items = request['items']
+name = request['operation']
+if phase == 'preflight':
+    missing = [item['name'] for item in items if not verify(refs, item['name'], item)]
+    if missing: os.mkdir(name, 0o700, dir_fd=imports)
+    print(json.dumps(missing))
+else:
+    stage = os.open(name, flags, dir_fd=imports)
+    try:
+        if phase == 'commit':
+            missing = []
+            for item in items:
+                if not verify(refs, item['name'], item):
+                    if not verify(stage, item['name'], item): raise RuntimeError('Reference staging file is absent')
+                    missing.append(item)
+            created = []
+            try:
+                for item in missing:
+                    os.link(item['name'], item['name'], src_dir_fd=stage, dst_dir_fd=refs, follow_symlinks=False)
+                    created.append(item['name'])
+                    fd = os.open(item['name'], os.O_RDONLY | os.O_NOFOLLOW, dir_fd=refs)
+                    try: os.fchmod(fd, 0o444); os.fsync(fd)
+                    finally: os.close(fd)
+                    if not verify(refs, item['name'], item): raise RuntimeError('Published reference file is absent')
+                os.fsync(refs)
+            except BaseException:
+                for created_name in created: os.unlink(created_name, dir_fd=refs)
+                raise
+            print('references-ready')
+        elif phase != 'cleanup': raise RuntimeError('Unsupported reference import phase')
+    finally:
+        for entry in os.listdir(stage): os.unlink(entry, dir_fd=stage)
+        os.close(stage)
+        os.rmdir(name, dir_fd=imports)
+`;
+/**
+ * Import validated originals into content-addressed guest files without overwriting.
+ * Read-only mode must be enforced by the embedding host before calling this writer.
+ */
+export async function importPalReferenceImages(references, options) {
+    if (!options.sandbox || typeof options.assertCurrentAdmission !== 'function')
+        throw new TypeError('Reference import requires a sandbox and a current admission check.');
+    const root = options.sandbox.rootDir;
+    if (!posix.isAbsolute(root) || root === '/' || root.includes('\\') || root.includes('\0'))
+        throw new Error('Reference import requires an owned POSIX guest working directory.');
+    // Public JavaScript callers cannot forge a prepared object to choose a filename
+    // or bypass image bounds. Recompute every digest and preserve only its position.
+    const verified = preparePalReferenceImages(references.map((reference) => ({
+        type: 'image',
+        mediaType: reference.mediaType,
+        data: reference.data,
+    }))).map((reference, index) => {
+        const original = references[index];
+        if (!original ||
+            !Number.isSafeInteger(original.attachmentIndex) ||
+            original.attachmentIndex < 1 ||
+            original.sha256 !== reference.sha256 ||
+            original.bytes !== reference.bytes)
+            throw new Error('Reference image metadata does not match its original bytes.');
+        return { ...reference, attachmentIndex: original.attachmentIndex };
+    });
+    if (verified.length === 0)
+        return [];
+    const operation = randomUUID();
+    const entries = new Map(verified.map((reference) => [
+        `${reference.sha256}.${EXTENSIONS[reference.mediaType]}`,
+        reference,
+    ]));
+    const items = [...entries].map(([name, reference]) => ({
+        name,
+        sha256: reference.sha256,
+        bytes: reference.bytes,
+    }));
+    const assertCurrent = async () => {
+        options.signal?.throwIfAborted();
+        await options.assertCurrentAdmission();
+        options.signal?.throwIfAborted();
+    };
+    const execute = async (phase) => {
+        await assertCurrent();
+        const result = await options.sandbox.exec('python3', ['-c', IMPORT_SCRIPT, JSON.stringify({ phase, root, operation, items })], { signal: options.signal });
+        await assertCurrent();
+        if (result.exitCode !== 0 || result.timedOut || result.signal)
+            throw new Error(`Guest reference import ${phase} failed; no manifest was published.`);
+        return result.stdout.trim();
+    };
+    const output = await execute('preflight');
+    const missing = JSON.parse(output);
+    if (!Array.isArray(missing) ||
+        missing.some((name) => typeof name !== 'string' || !entries.has(name)))
+        throw new Error('The guest returned an invalid reference import preflight.');
+    if (missing.length > 0) {
+        let committed = false;
+        try {
+            for (const name of new Set(missing)) {
+                await assertCurrent();
+                const reference = entries.get(name);
+                if (!reference)
+                    throw new Error('The guest requested an unknown reference.');
+                await options.sandbox.writeFile(posix.join(root, '.namzu', 'reference-imports', operation, name), Buffer.from(reference.data, 'base64'));
+                await assertCurrent();
+            }
+            if ((await execute('commit')) !== 'references-ready')
+                throw new Error('The guest did not confirm reference publication.');
+            committed = true;
+        }
+        finally {
+            // A revoked admission never authorizes another operation merely for cleanup.
+            // An interrupted scratch directory can remain, but is never a reference receipt.
+            if (!committed && !options.signal?.aborted) {
+                try {
+                    await execute('cleanup');
+                }
+                catch {
+                    // Preserve the original import failure; guest teardown owns remaining scratch.
+                }
+            }
+        }
+    }
+    return Object.freeze(verified.map(({ data: _data, ...reference }) => Object.freeze({
+        ...reference,
+        path: posix.join(root, '.namzu', 'references', `${reference.sha256}.${EXTENSIONS[reference.mediaType]}`),
+    })));
+}
+/** Explicit writer that passes through the ordinary tool permission/review policy. */
+export function createPalReferenceImageTool(options) {
+    return defineTool({
+        name: 'import_reference_images',
+        description: 'Copy the original inline reference images attached to the current operator input into this Pal computer for use by any application. Takes no filenames, URLs or base64. Returns a verified attachment-position-to-guest-file manifest only after the original bytes exist there. Existing matching references are reused and never overwritten. Stored references need a host resolver. An attachment visible to the model is not yet a guest file; call this tool before using it in an application. Requires permission to write files.',
+        inputSchema: z.object({}).strict(),
+        category: 'filesystem',
+        permissions: ['file_write'],
+        readOnly: false,
+        destructive: false,
+        concurrencySafe: false,
+        maxRetries: 0,
+        async execute(_input, context) {
+            if (!context.sandbox)
+                throw new Error('Reference images can only be imported into an admitted Pal computer.');
+            if (context.permissionContext?.mode === 'plan')
+                throw new Error('Reference image import writes files and is unavailable in read-only plan mode.');
+            await options.assertCurrentAdmission(context);
+            const references = preparePalReferenceImages(options.attachments());
+            if (references.length === 0)
+                throw new Error('The current operator input has no inline reference images to import.');
+            const receipt = await importPalReferenceImages(references, {
+                sandbox: context.sandbox,
+                assertCurrentAdmission: () => options.assertCurrentAdmission(context),
+                signal: context.abortSignal,
+            });
+            return {
+                success: true,
+                output: JSON.stringify({ references: receipt }),
+                data: { references: receipt },
+            };
+        },
+    });
+}
+//# sourceMappingURL=reference-images.js.map

package/dist/pals/reference-images.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-images.js","sourceRoot":"","sources":["../../src/pals/reference-images.ts"],"names":[],"mappings":"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"}

package/dist/pals/runtime.d.ts

@@ -0,0 +1,46 @@
+import type { ComputerUseResult } from '../types/computer-use/index.js';
+import { type PalLifecycleListener } from './lifecycle.js';
+import type { PalAdmission, PalAdmissionRequest, PalComputerControlState, PalComputerInput, PalComputerScreenStream, PalConversationAdmission, PalEnvironmentLease, PalRuntimeOptions } from './types.js';
+export declare class PalUnavailableError extends Error {
+    readonly name = "PalUnavailableError";
+}
+/** One host-owned local computer and one active input controller per Pal. */
+export declare class PalRuntime {
+    private readonly options;
+    private readonly computers;
+    private readonly starting;
+    private readonly controllers;
+    private readonly conversations;
+    private readonly lifecycle;
+    private readonly stopping;
+    private readonly freshScreenRequired;
+    private readonly controlOperations;
+    private readonly failures;
+    private closing;
+    private closed;
+    constructor(options: PalRuntimeOptions);
+    /** Live observations only. Unsubscribe does not stop the Pal or its computer. */
+    onLifecycle(listener: PalLifecycleListener): () => void;
+    computer(palId: string): PalEnvironmentLease | null;
+    computerError(palId: string): string | null;
+    /** Trusted host observation only. The credentials do not grant guest input authority. */
+    computerScreenStream(palId: string, generation: number): PalComputerScreenStream;
+    /** Actual provider authority, including a transition reserved by this runtime. */
+    computerControl(palId: string): PalComputerControlState;
+    busy(palId: string): boolean;
+    /** Actual guest lifecycle/control transition, independent of model-only chat. */
+    computerChanging(palId: string): boolean;
+    private ownedControl;
+    private controlOperation;
+    takeOver(palId: string, generation: number): Promise<void>;
+    returnControl(palId: string, generation: number): Promise<void>;
+    executeOperatorInput(palId: string, generation: number, input: PalComputerInput): Promise<ComputerUseResult>;
+    startComputer(palId: string, signal?: AbortSignal): Promise<PalEnvironmentLease>;
+    stopComputer(palId: string): Promise<void>;
+    /** Admit model conversation without starting or borrowing any computer. */
+    admitConversation(input: PalAdmissionRequest): Promise<PalConversationAdmission>;
+    admit(request: PalAdmissionRequest): Promise<PalAdmission>;
+    private admitComputer;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/pals/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/pals/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGX,iBAAiB,EACjB,MAAM,gCAAgC,CAAA;AACvC,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAC/E,OAAO,KAAK,EACX,YAAY,EACZ,mBAAmB,EAEnB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,EACjB,MAAM,YAAY,CAAA;AAEnB,qBAAa,mBAAoB,SAAQ,KAAK;IAC7C,SAAkB,IAAI,yBAAwB;CAC9C;AA0ID,6EAA6E;AAC7E,qBAAa,UAAU;IAkBV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAjBpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyC;IACnE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkD;IAC3E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAGzB;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAyD;IACvF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAoB;IACxD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAG/B;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,MAAM,CAAQ;gBACO,OAAO,EAAE,iBAAiB;IAEvD,iFAAiF;IACjF,WAAW,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAIvD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAMnD,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAI3C,yFAAyF;IACzF,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,uBAAuB;IA6ChF,kFAAkF;IAClF,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,uBAAuB;IAavD,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAW5B,iFAAiF;IACjF,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAGxC,OAAO,CAAC,YAAY;YAuBN,gBAAgB;IAqBxB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW1D,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/D,oBAAoB,CACzB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,gBAAgB,GACrB,OAAO,CAAC,iBAAiB,CAAC;IAevB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAkFhF,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BhD,2EAA2E;IACrE,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,wBAAwB,CAAC;IA2EhF,KAAK,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC;YAGlD,aAAa;IA4FrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAiC5B"}