Files
marqdo/lib/foreign.mq.md
T
cflmyandCursor 142ab523d6 release: v2.3.0 Foreign Strong session/handle/replay/arity
Opaque session handles, affine close, replay_check vs oracle journal,
table arity refuse, and Ω∈V_safe gate for the Strong foreign narrative.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-01 14:46:08 +08:00

6.7 KiB

markup, title, description, import
markup title description import
occlusion lib/foreign Run bound code fences and inline sources via local interpreters
table
lib/table.mq.md

Run bound code fences and inline sources via local interpreters.

set_cmd

+ `lang`
+ `cmd`
+ `args`=None

Bind interpreter command cmd for language lang; optional extra argv.

> host_foreign_set_cmd lang=lang cmd=cmd args=args

run

+ `code`
+ `stdin`=None
+ `env`=None
+ `cwd`=None
+ `timeout`=None
+ `args`=None
+ `max_output`=None

Run a bound code fence value; optional stdin, env map, cwd, timeout (seconds), extra argv and output cap. Returns stdout text; non-zero exit is an error.

Caller: [foreign.run] code=block

> host_foreign_run code=code stdin=stdin env=env cwd=cwd timeout=timeout args=args max_output=max_output

run_lang

+ `lang`
+ `source`
+ `stdin`=None
+ `env`=None
+ `cwd`=None
+ `timeout`=None
+ `args`=None
+ `max_output`=None

Run source text with language lang; same options as run.

> host_foreign_run_lang lang=lang source=source stdin=stdin env=env cwd=cwd timeout=timeout args=args max_output=max_output

invoke

+ `code`=None
+ `lang`=None
+ `source`=None
+ `stdin`=None
+ `input`=None
+ `env`=None
+ `cwd`=None
+ `timeout`=None
+ `args`=None
+ `output`=auto
+ `max_output`=None
+ `cmd`=None
+ `keep`=False

Run code or lang+source and return a record map instead of raising on process failure. Fields: ok, code, stdout, stderr, ms, lang, cmd, timed_out, truncated, result, result_error, error, script, cached.

input is encoded as JSON on stdin (mutually exclusive with stdin). output is auto | text | json | lines. cmd overrides the interpreter for this call.

> host_foreign_invoke code=code lang=lang source=source stdin=stdin input=input env=env cwd=cwd timeout=timeout args=args output=output max_output=max_output cmd=cmd keep=keep

probe

+ `lang`=None

Probe one language, or every known language when lang is omitted. Returns {lang, cmd, path, ok, version, error} (a list when lang is omitted).

> host_foreign_probe lang=lang

register

+ `lang`
+ `cmd`=None
+ `args`=None
+ `template`=None
+ `ext`=None
+ `env`=None
+ `version_args`=None

Register a language invocation. Provide cmd (+args) or template (placeholders {file}, {dir}, {base}, {inline}, {lang}, {cwd}); they are mutually exclusive.

> host_foreign_register lang=lang cmd=cmd args=args template=template ext=ext env=env version_args=version_args

unset

+ `lang`

Remove a process-local registration. Presets/config/env still apply.

> host_foreign_unset lang=lang

load_config

+ `path`=None

Load .marqdo/foreign.toml (or an explicit path); returns the number of language tables read.

> host_foreign_load_config path=path

call

+ `code`=None
+ `lang`=None
+ `source`=None
+ `input`=None
+ `stdin`=None
+ `env`=None
+ `cwd`=None
+ `timeout`=None
+ `args`=None

JSON-in / JSON-out call: encode input on stdin, parse stdout JSON and return the value (empty stdout -> None). Raises on process failure or invalid JSON.

> host_foreign_call code=code lang=lang source=source input=input stdin=stdin env=env cwd=cwd timeout=timeout args=args

run_many

+ `runs`
+ `concurrency`=4

Run a list of code values or invoke-option maps in parallel; returns records in input order. One failing item does not stop the others.

> host_foreign_run_many runs=runs concurrency=concurrency

call_many

+ `inputs`
+ `code`=None
+ `lang`=None
+ `source`=None
+ `cmd`=None
+ `env`=None
+ `cwd`=None
+ `timeout`=None
+ `args`=None
+ `max_output`=None
+ `concurrency`=4

Apply one code/function to each input in parallel; returns parsed JSON results in input order. Raises with the failing index after all workers finish.

> host_foreign_call_many inputs=inputs code=code lang=lang source=source cmd=cmd env=env cwd=cwd timeout=timeout args=args max_output=max_output concurrency=concurrency

session

+ `kernels`=None
+ `cells`=None
+ `values`=None
+ `inputs`=None

Declare a document view session. kernels and cells are ordinary tables: kernels are |名称|语言|命令| (ZH or EN), cells are |单元|内核|. Returns a foreign session handle consumed by view; without this handle the view has no persistent kernel state.

p = > table.empty_map p = > table.put in=p at="kind" value="foreign-session" p = > table.put in=p at="kernels" value=kernels p = > table.put in=p at="cells" value=cells p = > table.put in=p at="values" value=values p = > table.put in=p at="inputs" value=inputs p

session_open

+ `lang`
+ `cmd`=None
+ `env`=None
+ `cwd`=None
+ `timeout`=None

Start a persistent Python/Node kernel; returns an opaque handle value. Text fabrications are refused by session ops; handles cannot cross the JSON bridge. timeout is the default per-eval timeout.

> host_foreign_session_open lang=lang cmd=cmd env=env cwd=cwd timeout=timeout

session_eval

+ `id`
+ `code`=None
+ `source`=None
+ `input`=None
+ `stdin`=None
+ `timeout`=None

Evaluate code (a code value) or source text in session id; returns a record with id/alive. input is JSON-encoded for the kernel; stdin is raw program stdin for this evaluation.

> host_foreign_session_eval id=id code=code source=source input=input stdin=stdin timeout=timeout

session_set

+ `id`
+ `name`
+ `value`

Set one kernel variable from a Marqdo value (JSON copy).

> host_foreign_session_set id=id name=name value=value

session_get

+ `id`
+ `name`

Read one kernel variable as a Marqdo value.

> host_foreign_session_get id=id name=name

session_names

+ `id`

List kernel variable names.

> host_foreign_session_names id=id

session_close

+ `id`

Consume (affine close) a live session handle: kill and remove it. Returns True on success. Closing an unknown or already-closed id is a fault (foreign session … not found), matching use-after-close on eval/set/get.

> host_foreign_session_close id=id

session_interrupt

+ `id`

Interrupt the current evaluation of a persistent kernel. The session remains usable for the next evaluation when the worker supports interruption.

> host_foreign_session_interrupt id=id

session_list

List live sessions with id/lang/cmd/evals/alive/started_ms.

> host_foreign_session_list

langs

List configured foreign languages.

> host_foreign_langs